sepafm 0.1.5 → 1.0.0

data/lib/sepa/response.rb

@@ -1,10 +1,27 @@
 module Sepa
+
+  # Handles soap responses got back from the bank. Bank specific functionality is defined in
+  # subclasses. Handles i.e. logic to make sure the response's integrity has not been compromised
+  # and has methods to extract content from the response.
   class Response
     include ActiveModel::Validations
     include Utilities
     include ErrorMessages
 
-    attr_reader :soap, :error, :command
+    # The raw soap response in xml
+    #
+    # @return [String]
+    attr_reader :soap
+
+    # Possible Savon::Error with which the {Response} was initialized
+    #
+    # @return [String]
+    attr_reader :error
+
+    # The command with which the response was initialized
+    #
+    # @return [Symbol]
+    attr_reader :command
 
     validate  :document_must_validate_against_schema
     validate  :client_errors
@@ -13,6 +30,16 @@ module Sepa
     validate  :verify_signature
     validate  :verify_certificate
 
+    # Initializes the response with a options hash
+    #
+    # @param hash [Hash] Hash of options
+    # @example Possible keys in options hash
+    #   {
+    #     response: "something",
+    #     command: :get_user_info,
+    #     error: "I'm error",
+    #     encryption_private_key: OpenSSL::PKey::RSA
+    #   }
     def initialize(hash = {})
       @soap = hash[:response]
       @command = hash[:command]
@@ -20,13 +47,27 @@ module Sepa
       @encryption_private_key = hash[:encryption_private_key]
     end
 
+    # Returns the soap of the response as a Nokogiri document
+    #
+    # @return [Nokogiri::XML] The soap as Nokogiri document
     def doc
       @doc ||= xml_doc @soap
     end
 
-    # Verifies that all digest values in the response match the actual ones.
-    # Takes an optional verbose parameter to show which digests didn't match
-    # i.e. verbose: true
+    # Verifies that all digest values in the response match the actual ones. Takes an optional
+    # verbose parameter to show which digests didn't match. The digest embedded in the document are
+    # first retrieved with {#find_digest_values} method and if none are found, false is returned.
+    # After this, nodes to calculate hashes from are retrieved and hashes using
+    # {#find_nodes_to_verify} method and after this the calculated digests are compared with the
+    # embedded ones. If the all match, true is returned. If some digests failed to verify and
+    # verbose parameter was passed, digests that failed to verify are printed to screen and
+    # false is returned. Otherwise just false is returned.
+    #
+    # @param options [Hash]
+    # @return [false] if hashes don't match or aren't found
+    # @return [true] if hashes match
+    # @example Options hash
+    #   { verbose: true }
     def hashes_match?(options = {})
       digests = find_digest_values
 
@@ -53,17 +94,28 @@ module Sepa
       false
     end
 
-    # Verifies the signature by extracting the public key from the certificate
-    # embedded in the soap header and verifying the signature value with that.
+    # Verifies the signature by extracting the public key from the certificate embedded in the
+    # response and verifying the signature value with that. Makes a call to {#validate_signature}
+    # to do the actual verification. Passes `:exclusive` to {#validate_signature} so that exclusive
+    # mode of xml canonicalization is used.
+    #
+    # @return [true] if signature is valid
+    # @return [false] if signature fails to verify
     def signature_is_valid?
       validate_signature(doc, certificate, :exclusive)
     end
 
-    # Gets the application response from the response as an xml document
+    # Gets the application response from the response as an xml document. Makes a call to
+    # {#extract_application_response} to do the extraction.
+    #
+    # @return [String] The application response as a raw xml document
     def application_response
       @application_response ||= extract_application_response(BXD)
     end
 
+    # Returns the file references in a download file list response
+    #
+    # @return [Array] File references
     def file_references
       return unless @command == :download_file_list
 
@@ -74,12 +126,23 @@ module Sepa
       end
     end
 
+    # Returns the certificate embedded in the response
+    #
+    # @return [OpenSSL::X509::Certificate] if the certificate is found
+    # @return [nil] if the certificate can't be found
+    # @raise [OpenSSL::X509::CertificateError] if the certificate cannot be processed
     def certificate
       @certificate ||= begin
         extract_cert(doc, 'BinarySecurityToken', OASIS_SECEXT)
       end
     end
 
+    # Returns the content of the response according to {#command}. When command is `:download_file`,
+    # content is returned as a base64 encoded string, when {#command} is `:download_file_list`, the
+    # content is returned as xml, when {#command} is `:get_user_info`, the content is returned as xml
+    # and when {#command} is `:upload_file`, content is returned as xml
+    #
+    # @return [String] the content as xml or base64 encoded string
     def content
       @content ||= begin
         xml = xml_doc(application_response)
@@ -103,22 +166,35 @@ module Sepa
       end
     end
 
+    # Returns the raw soap as xml
+    #
+    # @return [String]
     def to_s
       @soap
     end
 
+    # @abstract
     def bank_encryption_certificate; end
 
+    # @abstract
     def bank_signing_certificate; end
 
+    # @abstract
     def bank_root_certificate; end
 
+    # @abstract
     def own_encryption_certificate; end
 
+    # @abstract
     def own_signing_certificate; end
 
+    # @abstract
     def ca_certificate; end
 
+    # Returns the response code of the response
+    #
+    # @return [String] if the response code can be found
+    # @return [nil] if the response code cannot be found
     def response_code
       node = doc.at('xmlns|ResponseCode', xmlns: BXD)
       node.content if node
@@ -126,8 +202,10 @@ module Sepa
 
     private
 
-      # Finds all reference nodes with digest values in the document and returns
-      # a hash with uri as the key and digest as the value.
+      # Finds all reference nodes with digest values in the document and returns a hash with uri as
+      # the key and digest as the value.
+      #
+      # @return [Hash] hash of digests with reference uri as the key
       def find_digest_values
         references = {}
         reference_nodes = doc.css('xmlns|Reference', xmlns: DSIG)
@@ -142,8 +220,11 @@ module Sepa
         references
       end
 
-      # Finds nodes to verify by comparing their id's to the uris' in the
-      # references hash.
+      # Finds nodes to verify by comparing their id's to the uris' in the references hash. Then
+      # calculates the hashes of those nodes and returns them in a hash
+      #
+      # @param references [Hash]
+      # @return [Hash] hash of calculated digests with reference uri as the key
       def find_nodes_to_verify(references)
         nodes = {}
 
@@ -157,12 +238,18 @@ module Sepa
         nodes
       end
 
+      # Validates the document against soap schema unless {#error} is present or command is
+      # `:get_bank_certificate`
       def document_must_validate_against_schema
         return if @error || command.to_sym == :get_bank_certificate
 
         check_validity_against_schema(doc, 'soap.xsd')
       end
 
+      # Extracts and returns application response from the response
+      #
+      # @return [String] application response as raw xml if it can be found
+      # @return [nil] if application response cannot be found
       def extract_application_response(namespace)
         ar_node = doc.at('xmlns|ApplicationResponse', xmlns: namespace)
         if ar_node
@@ -170,15 +257,22 @@ module Sepa
         end
       end
 
+      # Handles errors that have been passed from client
       def client_errors
         client_error = error.to_s
         errors.add(:base, client_error) unless client_error.empty?
       end
 
+      # Find node by it's reference URI in soap header
+      #
+      # @param uri [String] the node's URI
+      # @return [Nokogiri::XML::Node]
       def find_node_by_uri(uri)
         doc.at("[xmlns|Id='#{uri}']", xmlns: OASIS_UTILITY)
       end
 
+      # Validates response code in response. "00" and "24" are currently considered valid.
+      # Validation is not run if {#error} is present
       def validate_response_code
         return if @error
 
@@ -187,14 +281,19 @@ module Sepa
         end
       end
 
+      # Validates hashes in the response. {#hashes_match?} must return true for validation to pass.
+      # Is not run if {#error} is present or response code is not ok.
       def validate_hashes
         return if @error
         return unless response_code_is_ok?
+
         unless hashes_match?
           errors.add(:base, HASH_ERROR_MESSAGE)
         end
       end
 
+      # Validate signature in the response. Validation is not run if {#error} is present or response
+      # is not ok.
       def verify_signature
         return if @error
         return unless response_code_is_ok?
@@ -204,6 +303,9 @@ module Sepa
         end
       end
 
+      # Validates certificate in the soap. The certificate must be present and signed by the bank's
+      # root certificate for the validation to pass. Is not run if {#error} is present or response
+      # code is not ok.
       def verify_certificate
         return if @error
         return unless response_code_is_ok?
@@ -213,6 +315,11 @@ module Sepa
         end
       end
 
+      # Checks whether response code in the response is ok. Response code is considered ok if it is
+      # "00" or "24".
+      #
+      # @return [true] if response code is ok
+      # @return [false] if response code is not ok
       def response_code_is_ok?
         return true if %w(00 24).include? response_code
 

data/lib/sepa/soap_builder.rb

@@ -1,10 +1,20 @@
 module Sepa
+
+  # Builds a soap message with given parameters. This class is extended with proper bank module
+  # depending on bank.
   class SoapBuilder
     include Utilities
 
+    # Application request built with the same parameters as the soap
+    #
+    # @return [ApplicationRequest]
     attr_reader :application_request
 
-    # SoapBuilder creates the SOAP structure.
+    # Initializes the {SoapBuilder} with the params hash and then extends the {SoapBuilder} with the
+    # correct bank module. The {SoapBuilder} class is usually created by the client which handles
+    # parameter validation.
+    #
+    # @param params [Hash] options hash
     def initialize(params)
       @bank                        = params[:bank]
       @own_signing_certificate     = params[:own_signing_certificate]
@@ -27,13 +37,16 @@ module Sepa
       find_correct_bank_extension
     end
 
+    # Returns the soap as raw xml
+    #
+    # @return [String] the soap as xml
     def to_xml
-      # Returns a complete SOAP message in xml format
       find_correct_build.to_xml
     end
 
     private
 
+      # Extends the class with proper module depending on bank
       def find_correct_bank_extension
         case @bank
         when :danske
@@ -43,6 +56,13 @@ module Sepa
         end
       end
 
+      # Calculates digest hash for the given node in the given document. The node is canonicalized
+      # exclusively before digest calculation.
+      #
+      # @param doc [Nokogiri::XML] Document that contains the node
+      # @param node [String] The name of the node
+      # @return [String] the base64 encoded string
+      # @todo remove this method and use {Utilities#calculate_digest}
       def calculate_digest(doc, node)
         sha1 = OpenSSL::Digest::SHA1.new
         node = doc.at_css(node)
@@ -55,6 +75,14 @@ module Sepa
         encode(sha1.digest(canon_node)).gsub(/\s+/, "")
       end
 
+      # Calculates signature for the given node in the given document. Uses the signing private key
+      # given to SoapBuilder for the signing. The node is canonicalized exclusively before signature
+      # calculation.
+      #
+      # @param doc [Nokogiri::XML] Document that contains the node
+      # @param node [String] Name of the node to calculate signature from
+      # @return [String] the base64 encoded signature
+      # @todo refactor to use canonicalization from utilities
       def calculate_signature(doc, node)
         sha1 = OpenSSL::Digest::SHA1.new
         node = doc.at_css(node)
@@ -68,21 +96,43 @@ module Sepa
         encode(signature).gsub(/\s+/, "")
       end
 
+      # Loads soap header template to be later populated
+      #
+      # @return [Nokogiri::XML] the header as Nokogiri document
       def load_header_template
         path = File.open("#{SOAP_TEMPLATE_PATH}/header.xml")
         Nokogiri::XML(path)
       end
 
+      # Sets value to a node's content in the given document
+      # @param doc [Nokogiri::XML] The document that contains the node
+      # @param node [String] The name of the node which value is about to be set
+      # @param value [#to_s] The value which will be set to the node
       def set_node(doc, node, value)
         doc.at_css(node).content = value
       end
 
+      # Adds soap body to header template
+      #
+      # @return [Nokogiri::XML] the soap with added body as a nokogiri document
       def add_body_to_header
         body = @template.at_css('env|Body')
         @header_template.root.add_child(body)
         @header_template
       end
 
+      # Add needed information to soap header. Mainly security related stuff. The process is as
+      # follows:
+      # 1. The reference id of the security token is set using {#set_token_id} method
+      # 2. Created and expires timestamps are set. Expires is set to be 5 minutes after creation.
+      # 3. Timestamp reference id is set with {#set_node_id} method
+      # 4. The digest of timestamp node is calculated and set to correct node
+      # 5. The reference id of body is set with {#set_node_id}
+      # 6. The digest of body is calculated and set to correct node
+      # 7. The signature of SignedInfo node is calculated and added to correct node
+      # 8. Own signing certificate is formatted (Begin and end certificate removed and linebreaks
+      #    removed) and embedded in the soap
+      # @todo split into smaller methods
       def process_header
         set_token_id
 
@@ -108,6 +158,7 @@ module Sepa
         set_node(@header_template, 'wsse|BinarySecurityToken', formatted_cert)
       end
 
+      # Generates a random token id and sets it to correct node
       def set_token_id
         security_token_id = "token-#{SecureRandom.uuid}"
 

data/lib/sepa/utilities.rb

@@ -1,6 +1,13 @@
 module Sepa
+
+  # Contains utility methods that are used in this gem.
   module Utilities
 
+    # Calculates a SHA1 digest for a given node. Before the calculation, the node is canonicalized
+    # exclusively.
+    #
+    # @param node [Nokogiri::Node] the node which the digest is calculated from
+    # @return [String] the calculated digest
     def calculate_digest(node)
       sha1 = OpenSSL::Digest::SHA1.new
 
@@ -9,9 +16,12 @@ module Sepa
       encode(sha1.digest(canon_node)).gsub(/\s+/, "")
     end
 
-    # Takes a certificate, adds begin and end
-    # certificate texts and splits it into multiple lines so that OpenSSL
-    # can read it.
+    # Takes a certificate, adds begin and end certificate texts and splits it into multiple lines so
+    # that OpenSSL can read it.
+    #
+    # @param cert_value [#to_s] the certificate to be processed
+    # @return [String] the processed certificate
+    # @todo rename maybe because this seems more formatting than {#format_cert}
     def process_cert_value(cert_value)
       cert = "-----BEGIN CERTIFICATE-----\n"
       cert << cert_value.to_s.gsub(/\s+/, "").scan(/.{1,64}/).join("\n")
@@ -19,6 +29,13 @@ module Sepa
       cert << "-----END CERTIFICATE-----"
     end
 
+    # Removes begin and end certificate texts from a certificate and removes whitespaces to make the
+    # certificate read to be embedded in xml.
+    #
+    # @param cert [#to_s] The certificate to be formatted
+    # @return [String] the formatted certificate
+    # @todo rename maybe
+    # @see #process_cert_value
     def format_cert(cert)
       cert = cert.to_s
       cert = cert.split('-----BEGIN CERTIFICATE-----')[1]
@@ -26,12 +43,23 @@ module Sepa
       cert.gsub!(/\s+/, "")
     end
 
+    # Removes begin and end certificate request texts from a certificate signing request and removes
+    # whitespaces
+    #
+    # @param cert_request [String] the certificate request to be formatted
+    # @return [String] the formatted certificate request
+    # @todo rename
     def format_cert_request(cert_request)
       cert_request = cert_request.split('-----BEGIN CERTIFICATE REQUEST-----')[1]
       cert_request = cert_request.split('-----END CERTIFICATE REQUEST-----')[0]
       cert_request.gsub!(/\s+/, "")
     end
 
+    # Validates whether a doc is valid against a schema. Adds error using ActiveModel validations if
+    # document is not valid against the schema.
+    #
+    # @param doc [Nokogiri::XML::Document] the document to validate
+    # @param schema [String] name of the schema file in {SCHEMA_PATH}
     def check_validity_against_schema(doc, schema)
       Dir.chdir(SCHEMA_PATH) do
         xsd = Nokogiri::XML::Schema(IO.read(schema))
@@ -41,8 +69,16 @@ module Sepa
       end
     end
 
-    # Extracts a certificate from a document and return it as an OpenSSL X509 certificate
-    # Return nil is the node cannot be found
+    # Extracts a certificate from a document and returns it as an OpenSSL X509 certificate. Returns
+    # nil if the node cannot be found
+    #
+    # @param doc [Nokogiri::XML::Document] the document that contains the certificate node
+    # @param node [String] the name of the node that contains the certificate
+    # @param namespace [String] the namespace of the certificate node
+    # @return [OpenSSL::X509::Certificate] the extracted certificate if it is extracted successfully
+    # @return [nil] if the certificate cannot be found
+    # @raise [OpenSSL::X509::CertificateError] if there is a problem with the certificate
+    # @todo refactor not to fail
     def extract_cert(doc, node, namespace)
       cert_raw = doc.at("xmlns|#{node}", 'xmlns' => namespace)
 
@@ -56,10 +92,17 @@ module Sepa
         x509_certificate(cert)
       rescue => e
         fail OpenSSL::X509::CertificateError,
-             "The certificate could not be processed. It's most likely corrupted. OpenSSL had this to say: #{e}."
+             "The certificate could not be processed. It's most likely corrupted. " \
+             "OpenSSL had this to say: #{e}."
       end
     end
 
+    # Checks whether a certificate signing request is valid
+    #
+    # @param cert_request [#to_s] the certificate signing request
+    # @return [true] if the certificate signing request is valid
+    # @return [false] if the certificate signing request is not valid
+    # @todo rename
     def cert_request_valid?(cert_request)
       begin
         OpenSSL::X509::Request.new cert_request
@@ -70,6 +113,12 @@ module Sepa
       true
     end
 
+    # Loads a soap or application request xml template according to a parameter and command.
+    #
+    # @param template [String] path to a template directory. Currently supported values are defined
+    #   in contants {AR_TEMPLATE_PATH} and {SOAP_TEMPLATE_PATH}.
+    # @return [Nokogiri::XML::Document] the loaded template
+    # @raise [ArgumentError] if a template cannot be found for a command
     def load_body_template(template)
       path = "#{template}/"
 
@@ -95,49 +144,144 @@ module Sepa
       xml_doc(File.open(path))
     end
 
+    # Gets current utc time in iso-format
+    #
+    # @return [String] current utc time in iso-format
     def iso_time
       @iso_time ||= Time.now.utc.iso8601
     end
 
+    # Calculates an HMAC for a given pin and certificate signing request. Used by Nordea certificate
+    # requests.
+    #
+    # @param pin [#to_s] the one-time pin number got from bank
+    # @param csr [#to_s] the certificate signing request
+    # @return [String] the generated HMAC for the values
     def hmac(pin, csr)
       encode(OpenSSL::HMAC.digest('sha1', pin, csr)).chop
     end
 
+    # Converts a certificate signing request from base64 encoded string to binary string
+    #
+    # @param csr [#to_s] certificate signing request in base64 encoded format
+    # @return [String] the certificate signing request in binary format
     def csr_to_binary(csr)
       OpenSSL::X509::Request.new(csr).to_der
     end
 
+    # Canonicalizes a node inclusively
+    #
+    # @param doc [Nokogiri::XML::Document] the document that contains the node
+    # @param namespace [String] the namespace of the node
+    # @param node [String] name of the node
+    # @return [String] the canonicalized node if the node can be found
+    # @return [nil] if the node cannot be found
     def canonicalized_node(doc, namespace, node)
       content_node = doc.at("xmlns|#{node}", xmlns: namespace)
       content_node.canonicalize if content_node
     end
 
+    # Converts an xml string to a nokogiri document
+    #
+    # @param value [to_s] the xml document
+    # @return [Nokogiri::XML::Document] the xml document
     def xml_doc(value)
       Nokogiri::XML value
     end
 
+    # Decodes a base64 encoded string
+    #
+    # @param value [#to_s] the base64 encoded string
+    # @return [String] the decoded string
     def decode(value)
       Base64.decode64 value
     end
 
+    # Canonicalizes an xml node exclusively without comments
+    #
+    # @param value [Nokogiri::XML::Node, #canonicalize] the node to be canonicalized
+    # @return [String] the canonicalized node
     def canonicalize_exclusively(value)
       value.canonicalize(mode = Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0,
                          inclusive_namespaces = nil,
                          with_comments = false)
     end
 
+    # Creates a new OpenSSL X509 certificate from a string
+    #
+    # @param value [#to_s] the string from which to create the certificate
+    # @return [OpenSSL::X509::Certificate] the OpenSSL X509 certificate
+    # @example Example certificate to convert
+    #   "-----BEGIN CERTIFICATE-----
+    #   MIIDwTCCAqmgAwIBAgIEAX1JuTANBgkqhkiG9w0BAQUFADBkMQswCQYDVQQGEwJT
+    #   RTEeMBwGA1UEChMVTm9yZGVhIEJhbmsgQUIgKHB1YmwpMR8wHQYDVQQDExZOb3Jk
+    #   ZWEgQ29ycG9yYXRlIENBIDAxMRQwEgYDVQQFEws1MTY0MDYtMDEyMDAeFw0xMzA1
+    #   MDIxMjI2MzRaFw0xNTA1MDIxMjI2MzRaMEQxCzAJBgNVBAYTAkZJMSAwHgYDVQQD
+    #   DBdOb3JkZWEgRGVtbyBDZXJ0aWZpY2F0ZTETMBEGA1UEBRMKNTc4MDg2MDIzODCB
+    #   nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwtFEfAtbJuGzQwwRumZkvYh2BjGY
+    #   VsAMUeiKtOne3bZSeisfCq+TXqL1gI9LofyeAQ9I/sDm6tL80yrD5iaSUqVm6A73
+    #   9MsmpW/iyZcVf7ms8xAN51ESUgN6akwZCU9pH62ngJDj2gUsktY0fpsoVsARdrvO
+    #   Fk0fTSUXKWd6LbcCAwEAAaOCAR0wggEZMAkGA1UdEwQCMAAwEQYDVR0OBAoECEBw
+    #   2cj7+XMAMBMGA1UdIAQMMAowCAYGKoVwRwEDMBMGA1UdIwQMMAqACEALddbbzwun
+    #   MDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3Aubm9yZGVh
+    #   LnNlL0NDQTAxMA4GA1UdDwEB/wQEAwIFoDCBhQYDVR0fBH4wfDB6oHigdoZ0bGRh
+    #   cCUzQS8vbGRhcC5uYi5zZS9jbiUzRE5vcmRlYStDb3Jwb3JhdGUrQ0ErMDElMkNv
+    #   JTNETm9yZGVhK0JhbmsrQUIrJTI4cHVibCUyOSUyQ2MlM0RTRSUzRmNlcnRpZmlj
+    #   YXRlcmV2b2NhdGlvbmxpc3QwDQYJKoZIhvcNAQEFBQADggEBACLUPB1Gmq6286/s
+    #   ROADo7N+w3eViGJ2fuOTLMy4R0UHOznKZNsuk4zAbS2KycbZsE5py4L8o+IYoaS8
+    #   8YHtEeckr2oqHnPpz/0Eg7wItj8Ad+AFWJqzbn6Hu/LQhlnl5JEzXzl3eZj9oiiJ
+    #   1q/2CGXvFomY7S4tgpWRmYULtCK6jode0NhgNnAgOI9uy76pSS16aDoiQWUJqQgV
+    #   ydowAnqS9h9aQ6gedwbOdtkWmwKMDVXU6aRz9Gvk+JeYJhtpuP3OPNGbbC5L7NVd
+    #   no+B6AtwxmG3ozd+mPcMeVuz6kKLAmQyIiBSrRNa5OrTkq/CUzxO9WUgTnm/Sri7
+    #   zReR6mU=
+    #   -----END CERTIFICATE-----"
     def x509_certificate(value)
       OpenSSL::X509::Certificate.new value
     end
 
+    # Base64 encodes a given value
+    #
+    # @param value [#to_s] the value to be encoded
+    # @return [String] the base64 encoded string
     def encode(value)
       Base64.encode64 value
     end
 
+    # Creates a new OpenSSL RSA key from a string key
+    #
+    # @param key_as_string [to_s] the key as a string
+    # @return [OpenSSL::PKey::RSA] the OpenSSL RSA key
+    # @example Example key to convert
+    #   "-----BEGIN PRIVATE KEY-----
+    #   MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAMLRRHwLWybhs0MM
+    #   EbpmZL2IdgYxmFbADFHoirTp3t22UnorHwqvk16i9YCPS6H8ngEPSP7A5urS/NMq
+    #   w+YmklKlZugO9/TLJqVv4smXFX+5rPMQDedRElIDempMGQlPaR+tp4CQ49oFLJLW
+    #   NH6bKFbAEXa7zhZNH00lFylnei23AgMBAAECgYEAqt912/7x4jaQTrxlSELLFVp9
+    #   eo1BesVTiPwXvPpsGbbyvGjZ/ztkXNs9zZbh1aCGzZMkiR2U7F5GlsiprlIif4cF
+    #   6Xz7rCjaAs7iDRt9PjhjVuqNGR2I+VIIlbQ9XWFJ3lJFW3v7TIZ8JbLnn0XOFz+Z
+    #   BBSSGTK1zTNh4TBQtjECQQDe5M3uu9m4RwSw9R6GaDw/IFQZgr0oWSv0WIjRwvwW
+    #   nFnSX2lbkNAjulP0daGsmn7vxIpqZxPxwcrU4wFqTF5dAkEA38DnbCm3YfogzwLH
+    #   Nre2hBmGqjWarhtxqtRarrkgnmOd8W0Z1Hb1dSHrliUSVSrINbK5ZdEV15Rpu7VD
+    #   OePzIwJAPMslS+8alANyyR0iJUC65fDYX1jkZOPldDDNqIDJJxWf/hwd7WaTDpuc
+    #   mHmZDi3ZX2Y45oqUywSzYNtFoIuR1QJAZYUZuyqmSK77SdGB36K1DfSi9AFEQDC1
+    #   fwPAbTwTv6mFFPAiYxLiRZXxVPtW+QtjMXH4ymh2V4y/+GnCqbZyLwJBAJQSDAME
+    #   Sn4Uz7Zjk3UrBIbMYEv0u2mcCypwsb0nGE5/gzDPjGE9cxWW+rXARIs+sNQVClnh
+    #   45nhdfYxOjgYff0=
+    #   -----END PRIVATE KEY-----"
     def rsa_key(key_as_string)
       OpenSSL::PKey::RSA.new key_as_string
     end
 
+    # Generates a random id for a node in soap and sets it to the soap header
+    #
+    # @param document [Nokogiri::XML::Document] the document that contains the node
+    # @param namespace [String] the namespace of the node
+    # @param node [String] name of the node
+    # @param position [Integer] the soap header might contain many references and this parameter
+    # defines which reference is used. Numbering starts from 0.
+    # @return [String] the generated id of the node
+    # @todo create functionality to automatically add reference nodes to header so than position is
+    #   not needed
     def set_node_id(document, namespace, node, position)
       node_id = "#{node.downcase}-#{SecureRandom.uuid}"
       document.at("xmlns|#{node}", xmlns: namespace)['wsu:Id'] = node_id
@@ -146,6 +290,15 @@ module Sepa
       node_id
     end
 
+    # Verifies that a signature has been created with the private key of a certificate
+    #
+    # @param doc [Nokogiri::XML::Document] the document that contains the signature
+    # @param certificate [OpenSSL::X509::Certificate] the certificate to verify the signature
+    #   against
+    # @param canonicalization_method [Symbol] The canonicalization method that has been used to
+    #   canonicalize the SignedInfo node. Accepts `:normal` or `:exclusive`.
+    # @return [true] if signature verifies
+    # @return [false] if signature fails to verify or if it cannot be found
     def validate_signature(doc, certificate, canonicalization_method)
       node = doc.at('xmlns|SignedInfo', xmlns: DSIG)
 
@@ -165,6 +318,14 @@ module Sepa
       certificate.public_key.verify(OpenSSL::Digest::SHA1.new, signature, node)
     end
 
+    # Verifies that a certificate has been signed by the private key of a root certificate
+    #
+    # @param certificate [OpenSSL::X509::Certificate] the certificate to verify
+    # @param root_certificate [OpenSSL::X509::Certificate] the root certificate
+    # @return [true] if the certificate has been signed by the private key of the root certificate
+    # @return [false] if the certificate has not been signed by the private key of the root
+    #   certificate, the certificates are nil or the subject of the root certificate is not the
+    #   issuer of the certificate
     def verify_certificate_against_root_certificate(certificate, root_certificate)
       return false unless certificate && root_certificate
       return false unless root_certificate.subject == certificate.issuer

data/lib/sepa/version.rb

@@ -1,3 +1,5 @@
 module Sepa
-  VERSION = "0.1.5"
+
+  # The current version of the gem
+  VERSION = "1.0.0"
 end