Commit dc9b9e9

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 require 'saml/kit'
 
-puts "Enter Password:"
-password = STDIN.read.strip
-certificate, private_key = Saml::Kit::SelfSignedCertificate.new(password).create
+puts "Enter Passphrase:"
+passphrase = STDIN.read.strip
+certificate, private_key = Saml::Kit::SelfSignedCertificate.new(passphrase).create
 
 puts "** BEGIN File Format **"
 print certificate
@@ -18,5 +18,5 @@ puts private_key.inspect
 puts "***********************"
 
 puts
-puts "Private Key Password:"
-puts password.inspect
+puts "Private Key Passphrase:"
+puts passphrase.inspect

@@ -11,20 +11,20 @@ module Saml
     #     config.logger = Rails.logger
     #   end
     #
-    #   To specify global configuration it is best to do this in an initialize 
+    #   To specify global configuration it is best to do this in an initializer
     #   that runs at the start of the program.
     #
     #   Saml::Kit.configure do |configuration|
     #     configuration.issuer = "https://www.example.com/saml/metadata"
     #     configuration.generate_key_pair_for(use: :signing)
-    #     configuration.add_key_pair(ENV["X509_CERTIFICATE"], ENV["PRIVATE_KEY"], password: ENV['PRIVATE_KEY_PASSWORD'], use: :encryption)
+    #     configuration.add_key_pair(ENV["X509_CERTIFICATE"], ENV["PRIVATE_KEY"], passphrase: ENV['PRIVATE_KEY_PASSPHRASE'], use: :encryption)
     #   end
     class Configuration
       # The issuer or entity_id to use.
       attr_accessor :issuer
-      # The signature method to use when generating signatures (See {SAML::Kit::Builders::XmlSignature::SIGNATURE_METHODS})
+      # The signature method to use when generating signatures (See {Saml::Kit::Builders::XmlSignature::SIGNATURE_METHODS})
       attr_accessor :signature_method
-      # The digest method to use when generating signatures (See {SAML::Kit::Builders::XmlSignature::DIGEST_METHODS})
+      # The digest method to use when generating signatures (See {Saml::Kit::Builders::XmlSignature::DIGEST_METHODS})
       attr_accessor :digest_method
       # The metadata registry to use for searching for metadata associated with an issuer.
       attr_accessor :registry
@@ -47,19 +47,19 @@ module Saml
       #
       # @param certificate [String] the x509 certificate with public key.
       # @param private_key [String] the plain text private key.
-      # @param password [String] the password to decrypt the private key.
+      # @param passphrase [String] the password to decrypt the private key.
       # @param use [Symbol] the type of key pair, `:signing` or `:encryption`
-      def add_key_pair(certificate, private_key, password: '', use: :signing)
-        @key_pairs.push(KeyPair.new(certificate, private_key, password, use.to_sym))
+      def add_key_pair(certificate, private_key, passphrase: '', use: :signing)
+        @key_pairs.push(KeyPair.new(certificate, private_key, passphrase, use.to_sym))
       end
 
       # Generates a unique key pair that can be used for signing or encryption.
       #
       # @param use [Symbol] the type of key pair, `:signing` or `:encryption`
-      # @param password [String] the private key password to use.
-      def generate_key_pair_for(use:, password: SecureRandom.uuid)
-        certificate, private_key = SelfSignedCertificate.new(password).create
-        add_key_pair(certificate, private_key, password: password, use: use)
+      # @param passphrase [String] the private key passphrase to use.
+      def generate_key_pair_for(use:, passphrase: SecureRandom.uuid)
+        certificate, private_key = SelfSignedCertificate.new(passphrase).create
+        add_key_pair(certificate, private_key, passphrase: passphrase, use: use)
       end
 
       # Return each key pair for a specific use.

@@ -8,6 +8,7 @@ module Saml
     module Crypto
       DECRYPTORS = [ SimpleCipher, RsaCipher, OaepCipher, UnknownCipher ]
 
+      # @!visibility private
       def self.decryptor_for(algorithm, key)
         DECRYPTORS.find { |x| x.matches?(algorithm) }.new(algorithm, key)
       end

@@ -2,6 +2,31 @@ module Saml
   module Kit
     # The default metadata registry is used to fetch the metadata associated with an issuer or entity id.
     # The metadata associated with an issuer is used to verify trust for any SAML documents that are received.
+    #
+    # You can replace the default registry with your own at startup.
+    #
+    # Example:
+    #
+    #   class OnDemandRegistry
+    #    def initialize(original)
+    #      @original = original
+    #    end
+    #
+    #    def metadata_for(entity_id)
+    #      found = @original.metadata_for(entity_id)
+    #      return found if found
+    #
+    #      @original.register_url(entity_id, verify_ssl: Rails.env.production?)
+    #      @original.metadata_for(entity_id)
+    #    end
+    #   end
+    #
+    #   Saml::Kit.configure do |configuration|
+    #     configuration.issuer = ENV['ISSUER']
+    #     configuration.registry = OnDemandRegistry.new(configuration.registry)
+    #     configuration.logger = Rails.logger
+    #   end
+
     class DefaultRegistry
       def initialize(items = {})
         @items = items

@@ -1,6 +1,11 @@
 module Saml
   module Kit
     # This generates a fingerprint for an X509 Certificate.
+    #
+    #   certificate, _ = Saml::Kit::SelfSignedCertificate.new("password").create
+    #
+    #   puts Saml::Kit::Fingerprint.new(certificate).to_s
+    #   # B7:AB:DC:BD:4D:23:58:65:FD:1A:99:0C:5F:89:EA:87:AD:F1:D7:83:34:7A:E9:E4:88:12:DD:46:1F:38:05:93
     class Fingerprint
       # The OpenSSL::X509::Certificate
       attr_reader :x509

@@ -1,6 +1,11 @@
 module Saml
   module Kit
+    # This class is used primary for generating ID.
+    #https://www.w3.org/2001/XMLSchema.xsd
     class Id
+
+     # Generate an ID that conforms to the XML Schema.
+      # https://www.w3.org/2001/XMLSchema.xsd
       def self.generate
         "_#{SecureRandom.uuid}"
       end

@@ -2,6 +2,7 @@ module Saml
   module Kit
     # This class is used to parse the IDPSSODescriptor from a SAML metadata document.
     #
+    #  raw_xml = <<-XML
     #  <?xml version="1.0" encoding="UTF-8"?>
     #  <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_cfa24e2f-0ec0-4ee3-abb8-b2fcfe394c1c" entityID="">
     #    <IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
@@ -12,6 +13,19 @@ module Saml
     #      <saml:Attribute Name="id"/>
     #    </IDPSSODescriptor>
     #  </EntityDescriptor>
+    #  XML
+    #
+    #  metadata = Saml::Kit::IdentityProviderMetadata.new(raw_xml)
+    #  puts metadata.entity_id
+    #
+    # It can also be used to generate IDP metadata.
+    #
+    #   metadata = Saml::Kit::IdentityProviderMetadata.build do |builder|
+    #     builder.entity_id = "my-entity-id"
+    #   end
+    #   puts metadata.to_xml
+    #
+    # For more details on generating metadata see {Saml::Kit::Metadata}.
     class IdentityProviderMetadata < Metadata
       def initialize(xml)
         super("IDPSSODescriptor", xml)

@@ -1,10 +1,33 @@
 module Saml
   module Kit
-    # This class parses a LogoutRequest SAML document.
+    # This class can be used to parse a LogoutRequest SAML document.
+    #
+    #   document = Saml::Kit::LogoutRequest.new(raw_xml)
+    #
+    # It can also be used to generate a new LogoutRequest.
+    #
+    #   document = Saml::Kit::LogoutRequest.build do |builder|
+    #     builder.issuer = "issuer"
+    #   end
+    #
+    #   puts document.to_xml(pretty: true)
+    #
+    # See {Saml::Kit::Builders::LogoutRequest} for a list of available settings.
+    #
+    # This class can also be used to generate the correspondong LogoutResponse for a LogoutRequest.
+    #
+    #   document = Saml::Kit::LogoutRequest.new(raw_xml)
+    #   url, saml_params = document.response_for(binding: :http_post)
+    #
+    # See {#response_for} for more information.
     class LogoutRequest < Document
       include Requestable
       validates_presence_of :single_logout_service, if: :expected_type?
 
+      # A new instance of LogoutRequest
+      #
+      # @param xml [String] The raw xml string.
+      # @param configuration [Saml::Kit::Configuration] the configuration to use.
       def initialize(xml, configuration: Saml::Kit.configuration)
         super(xml, name: "LogoutRequest", configuration: configuration)
       end

@@ -1,6 +1,8 @@
 module Saml
   module Kit
     # This class is used to parse a LogoutResponse SAML document.
+    #
+    #   document = Saml::Kit::LogoutResponse.new(raw_xml)
     class LogoutResponse < Document
       include Respondable
 

@@ -161,7 +161,7 @@ module Saml
       #
       # @param algorithm [OpenSSL::Digest] the digest algorithm to use. E.g. `OpenSSL::Digest::SHA256`
       # @param signature [String] the signature to verify
-      # @param date [String] the data that is used to produce the signature.
+      # @param data [String] the data that is used to produce the signature.
       # @return [Saml::Kit::Certificate] the certificate that was used to produce the signature.
       def verify(algorithm, signature, data)
         signing_certificates.find do |certificate|

@@ -3,7 +3,7 @@ require "spec_helper"
 RSpec.describe Saml::Kit::Signatures do
   let(:configuration) do
     config = Saml::Kit::Configuration.new
-    config.add_key_pair(certificate, private_key, password: password, use: :signing)
+    config.add_key_pair(certificate, private_key, passphrase: passphrase, use: :signing)
     config
   end
 
@@ -21,8 +21,8 @@ RSpec.describe Saml::Kit::Signatures do
     x.sign(rsa_key, OpenSSL::Digest::SHA256.new)
     x.to_pem
   end
-  let(:private_key) { rsa_key.to_pem(OpenSSL::Cipher.new('des3'), password) }
-  let(:password) { "password" }
+  let(:private_key) { rsa_key.to_pem(OpenSSL::Cipher.new('des3'), passphrase) }
+  let(:passphrase) { "password" }
 
   it 'generates a signature' do
     options = {