sepafm 0.1.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3a2be4081eef183a47eae2d15775937b0afdeb7
-  data.tar.gz: 84c058d1e86826ddc435abb1aaa66ff4c73d4a7a
+  metadata.gz: 3071e7c2f8f6ab6f0fcff615a38f2d11517952da
+  data.tar.gz: fc8beef75e2f56ece35cccbd5101d1d2cc9af062
 SHA512:
-  metadata.gz: c4c73d8aa2da66edc8d915bd0690230e40c944e91acc5fc4de51134830ba5dc3e797d42d6b73a155632d1330c92b1d08cf7594589aa7aebad1b0c332cbdc6ff5
-  data.tar.gz: 4388e0c0357a779f637b731ff726f6cc81585c71bf88bddadeb160d37f7ea535d7e3f742c7f080cad204aa33b135ec7547ce75d31bcb26766e04723a68ea7dbc
+  metadata.gz: 734914613e29893e3c2188a0a3e390bbaf0ae0c170ef58a045f40261e3691c49fa9fc560753c2f5db83a0bd0ff013aab936d889746bc462d0b99571538ea318d
+  data.tar.gz: f0d4fac6bbb809d2750f2f6f501e5467398dd85ecef9ab8abbd6a2f6788734284ca12b0ebf066b0e87fc36637c1911c6ad2d1ec53a992abefcd4c110241c83a0

data/.yardopts

@@ -0,0 +1,6 @@
+lib/**/*.rb
+--private
+--readme readme.md
+--markup markdown
+--title "Documentation for Sepa"
+- LICENSE

data/lib/sepa/application_request.rb

@@ -1,7 +1,21 @@
 module Sepa
+
+  # Contains functionality to build the application request
+  #
+  # @todo Add return values for content modifying methods to signal whether they succeeded or not
   class ApplicationRequest
     include Utilities
 
+    # Initializes the {ApplicationRequest} with a params hash. The application request is usually
+    # initialized by the {SoapBuilder}. The xml template of the application request is also loaded
+    # here.
+    #
+    # @param params [Hash] the hash containing attributes needed by the {ApplicationRequest}. All
+    #   the key => value pairs in the hash are initialized as instance variables. The hash in the
+    #   initialization is usually the same as with {SoapBuilder} so the values have already been
+    #   validated by the client.
+    # @todo Consider not using instance_variable_set so that all the available instance variables
+    #   can easily be seen.
     def initialize(params = {})
       # Set all params as instance variables
       params.each do |key, value|
@@ -11,6 +25,11 @@ module Sepa
       @application_request = load_body_template AR_TEMPLATE_PATH
     end
 
+    # Sets the nodes in the application request, processes signature and then returns the
+    # application request as an xml document.
+    #
+    # @return [String] the application request as an xml document
+    # @todo This method is obviously doing too much
     def to_xml
       set_common_nodes
       set_nodes_contents
@@ -18,28 +37,48 @@ module Sepa
       @application_request.to_xml
     end
 
+    # Base64 encodes the whole application request
+    #
+    # @return [String] the base64 encoded application request
     def to_base64
       encode to_xml
     end
 
+    # Returns the application request as a Nokogiri document
+    #
+    # @return [Nokogiri::XML::Document] the application request as a nokogiri document
     def to_nokogiri
       Nokogiri::XML to_xml
     end
 
     private
 
+      # Sets node to value
+      #
+      # @param node [String] the name of the node which value is to be set
+      # @param value [#to_s] the value which is going to be set to the node
       def set_node(node, value)
         @application_request.at_css(node).content = value
       end
 
+      # Sets node to base64 encoded value
+      #
+      # @param node [String] name of the node
+      # @param value [#to_s] the value which is going to be set to the nodea base64 encoded
+      # @todo rename
       def set_node_b(node, value)
         set_node node, encode(value)
       end
 
+      # Converts {#command} to string, removes underscores and capitalizes it.
+      #
+      # @example Example input and output
+      #   :get_user_info --> GetUserInfo
       def pretty_command
         @command.to_s.split(/[\W_]/).map {|c| c.capitalize}.join
       end
 
+      # Determines which content setting method to call depending on {#command}
       def set_nodes_contents
         case @command
         when :create_certificate
@@ -57,6 +96,7 @@ module Sepa
         end
       end
 
+      # Sets nodes' values for download file request
       def set_download_file_nodes
         add_target_id_after 'FileReferences'
         set_node("Status", @status)
@@ -64,6 +104,11 @@ module Sepa
         set_node("FileReference", @file_reference)
       end
 
+      # Sets Danske Bank's get bank certificate request's contents
+      #
+      # @raise [OnlyWorksWithDanske] if {#bank} is not danske
+      # @todo Investigate a better way to set the bank's root certificate's serial instead of
+      #   hardcoding it
       def set_get_bank_certificate_nodes
         raise 'OnlyWorksWithDanske' if @bank != :danske
 
@@ -73,24 +118,34 @@ module Sepa
         set_node("elem|RequestId", @request_id)
       end
 
+      # Sets nodes' contents for upload file request
       def set_upload_file_nodes
         set_node_b("Content", @content)
         set_node("FileType", @file_type)
         add_target_id_after 'Environment'
       end
 
+      # Sets nodes' contents for download file list request
       def set_download_file_list_nodes
         add_target_id_after 'Environment'
         set_node("Status", @status)
         set_node("FileType", @file_type)
       end
 
+      # Sets nodes' contents for Nordea's get certificate request
+      #
+      # @todo Raise error if {#bank} is other than Nordea like in {#set_get_bank_certificate_nodes}
+      # @todo Check further into what service actually is
       def set_get_certificate_nodes
         set_node("Service", '')
         set_node("Content", format_cert_request(@signing_csr))
         set_node("HMAC", hmac(@pin, csr_to_binary(@signing_csr)))
       end
 
+      # Sets nodes' contents for Danske Bank's create certificate request. Environment is set to
+      # customertest if {#environment} is `:test`
+      #
+      # @todo Raise error if {#bank} is other than Nordea like in {#set_get_bank_certificate_nodes}
       def set_create_certificate_nodes
         set_node("tns|CustomerId", @customer_id)
         set_node("tns|KeyGeneratorType", 'software')
@@ -105,6 +160,8 @@ module Sepa
         set_node("tns|PIN", @pin)
       end
 
+      # Sets contents for nodes that are common to all requests except when {#command} is
+      # `:get_bank_certificate` or `:create_certificate`. {#environment} is upcased here.
       def set_common_nodes
         return if @command == :get_bank_certificate
         return if @command == :create_certificate
@@ -116,25 +173,48 @@ module Sepa
         set_node("Command", pretty_command)
       end
 
+      # Removes a node from {#application_request}
+      #
+      # @param node [String] name of the node to remove
+      # @param xmlns [String] the namespace of the node
+      # @todo Move to {Utilities} and move document to parameters
       def remove_node(node, xmlns)
         @application_request.at_css("xmlns|#{node}", 'xmlns' => xmlns).remove
       end
 
+      # Adds node to the root of the application request
+      #
+      # @todo Move to {Utilities} and move document to parameters
       def add_node_to_root(node)
         @application_request.root.add_child(node)
       end
 
+      # Calculates the digest of {#application_request}
+      #
+      # @todo Use the digest calculation method in {Utilities} instead of implementing the
+      #   functionality again here.
+      # @return [String] the base64 encoded digest of the {#application_request}
       def calculate_digest
         sha1 = OpenSSL::Digest::SHA1.new
         encode(sha1.digest(@application_request.canonicalize))
       end
 
+      # Adds value to signature node
+      #
+      # @param node [String] name of the signature node
+      # @param value [#to_s] the value to be set to the node
+      # @todo Remove this method and use {#set_node} method
       def add_value_to_signature(node, value)
         dsig = 'http://www.w3.org/2000/09/xmldsig#'
         sig = @application_request.at_css("dsig|#{node}", 'dsig' => dsig)
         sig.content = value
       end
 
+      # Calculates the application request's signature value. Uses {#signing_private_key} for the
+      # calculation.
+      #
+      # @return [String] the base64 encoded signature
+      # @todo Move to {Utilities}
       def calculate_signature
         sha1 = OpenSSL::Digest::SHA1.new
         dsig = 'http://www.w3.org/2000/09/xmldsig#'
@@ -143,6 +223,9 @@ module Sepa
         encode signature
       end
 
+      # Removes signature from the application request, calculates the application request's digest,
+      # calculates the signature and adds needed values to signature node. Also adds
+      # {#own_signing_certificate} to the signature node.
       def process_signature
         # No signature for Certificate Requests
         return if @command == :get_certificate
@@ -157,6 +240,10 @@ module Sepa
         add_value_to_signature('X509Certificate', format_cert(@own_signing_certificate))
       end
 
+      # Adds target id to the application request after a specific node because the schema defines a
+      # sequence. Target id is only added if {#bank} is `:nordea`
+      #
+      # @param node [String] the name of the node after which the target id node will be added
       def add_target_id_after(node)
         return unless @bank == :nordea
 

data/lib/sepa/application_response.rb

@@ -1,22 +1,39 @@
 module Sepa
+
+  # Contains functionality for the application response embedded in {Response}
+  # @todo Use functionality from this class more when validating response
   class ApplicationResponse
     include ActiveModel::Validations
     include Utilities
 
+    # The raw xml of the application response
+    #
+    # @return [String] the raw xml of the application response
     attr_reader :xml
 
     validate :response_must_validate_against_schema
 
+    # Initializes the {ApplicationResponse} with an application response xml and bank
+    #
+    # @param app_resp [#to_s] the application response xml
+    # @param bank [Symbol] the bank from which the application response came from
     def initialize(app_resp, bank)
       @xml = app_resp
       @bank = bank
     end
 
+    # The application response as a nokogiri xml document
+    #
+    # @return [Nokogiri::XML::Document] the application response as a nokogiri document
     def doc
       @doc ||= xml_doc @xml
     end
 
-    # Checks that the hash value reported in the signature matches the actual one.
+    # Checks that the hash value reported in the signature matches the one that is calculated
+    # locally
+    #
+    # @return [true] if hashes match
+    # @return [false] if hashes don't match
     def hashes_match?
       are = doc.clone
 
@@ -31,19 +48,36 @@ module Sepa
       false
     end
 
-    # Checks that the signature is signed with the private key of the certificate's public key.
+    # Checks that the signature has been calculated with the private key of the certificate's public
+    # key.
+    #
+    # @return [true] if signature can be verified
+    # @return [false] if signature fails to verify
     def signature_is_valid?
       validate_signature(doc, certificate, :normal)
     end
 
+    # Returns the raw xml of the application response
+    #
+    # @return [String] the raw xml of the application response
     def to_s
       @xml
     end
 
+    # The certificate which private key has been used to sign the application response
+    #
+    # @return [OpenSSL::X509::Certificate] if the certificate can be found
+    # @return [nil] if the certificate cannot be found
+    # @raise [OpenSSL::X509::CertificateError] if the certificate is not valid
     def certificate
       extract_cert(doc, 'X509Certificate', DSIG)
     end
 
+    # Checks whether the embedded certificate has been signed by the private key of the bank's root
+    # certificate. The root certificate used varies by bank.
+    #
+    # @return [true] if the certificate is trusted
+    # @return [false] if the certificate is not trusted
     def certificate_is_trusted?
       root_certificate =
         case @bank
@@ -58,6 +92,7 @@ module Sepa
 
     private
 
+      # Validates that the response is valid against the application response schema
       def response_must_validate_against_schema
         check_validity_against_schema(doc, 'application_response.xsd')
       end

data/lib/sepa/attribute_checks.rb

@@ -1,7 +1,13 @@
 module Sepa
+
+  # Contains functionality to check the attributes passed to {Client}. Uses
+  # ActiveModel::Validations for the actual validation.
   module AttributeChecks
     include ErrorMessages
 
+    # Commands which are allowed for a specific bank
+    #
+    # @return [Array<Symbol>] the commands which are allowed for {Client#bank}.
     def allowed_commands
       case bank
       when :nordea
@@ -14,10 +20,12 @@ module Sepa
       end
     end
 
+    # Checks that {Client#command} is included in {#allowed_commands}
     def check_command
       errors.add(:command, "Invalid command") unless allowed_commands.include? command
     end
 
+    # Checks that signing keys and certificates can be initialized properly.
     def check_keys
       return if [:get_certificate, :get_bank_certificate, :create_certificate].include? command
 
@@ -34,6 +42,7 @@ module Sepa
       end
     end
 
+    # Checks that signing certificate signing request can be initialized properly.
     def check_signing_csr
       return unless [:get_certificate, :create_certificate].include? command
 
@@ -42,6 +51,7 @@ module Sepa
       end
     end
 
+    # Checks that encryption certificate signing request can be initialized properly.
     def check_encryption_cert_request
       return unless command == :create_certificate
 
@@ -50,6 +60,7 @@ module Sepa
       end
     end
 
+    # Checks that {Client#file_type} is proper
     def check_file_type
       return unless [:upload_file, :download_file_list, :download_file].include? command
 
@@ -58,6 +69,7 @@ module Sepa
       end
     end
 
+    # Checks that {Client#target_id} is valid.
     def check_target_id
       return if [:get_user_info,
                  :get_certificate,
@@ -70,6 +82,11 @@ module Sepa
       check_presence_and_length(:target_id, 80, TARGET_ID_ERROR_MESSAGE)
     end
 
+    # Checks presence and length of an attribute
+    #
+    # @param attribute [Symbol] the attribute to validate
+    # @param length [Integer] the maximum length of the attribute
+    # @param error_message [#to_s] the error message to display if the validation fails
     def check_presence_and_length(attribute, length, error_message)
       check = true
       check &&= send(attribute)
@@ -80,6 +97,8 @@ module Sepa
       errors.add(attribute, error_message) unless check
     end
 
+    # Checks that the content (payload) of the request is somewhat correct. This validation is only
+    # run when {Client#command} is `:upload_file`.
     def check_content
       return unless command == :upload_file
 
@@ -91,12 +110,15 @@ module Sepa
       errors.add(:content, CONTENT_ERROR_MESSAGE) unless check
     end
 
+    # Checks that the {Client#pin} used in certificate requests in valid
     def check_pin
       return unless [:create_certificate, :get_certificate].include? command
 
       check_presence_and_length(:pin, 20, PIN_ERROR_MESSAGE)
     end
 
+    # Checks that {Client#environment} is included in {Client::ENVIRONMENTS}. Not run if
+    # {Client#command} is `:get_bank_certificate`.
     def check_environment
       return if command == :get_bank_certificate
 
@@ -105,12 +127,15 @@ module Sepa
       end
     end
 
+    # Checks that {Client#customer_id} is valid
     def check_customer_id
       unless customer_id && customer_id.respond_to?(:length) && customer_id.length.between?(1, 16)
         errors.add(:customer_id, CUSTOMER_ID_ERROR_MESSAGE)
       end
     end
 
+    # Checks that {Client#bank_encryption_certificate} can be initialized properly. Only run if
+    # {Client#bank} is `:danske` and {Client#command} is not `:get_bank_certificate`.
     def check_encryption_certificate
       return unless bank == :danske
       return if command == :get_bank_certificate
@@ -125,6 +150,7 @@ module Sepa
       errors.add(:bank_encryption_certificate, ENCRYPTION_CERT_ERROR_MESSAGE)
     end
 
+    # Checks that {Client#status} is included in {Client::STATUSES}.
     def check_status
       return unless [:download_file_list, :download_file].include? command
 
@@ -133,12 +159,16 @@ module Sepa
       end
     end
 
+    # Checks presence and length of {Client#file_reference} if {Client#command} is `:download_file`
     def check_file_reference
       return unless command == :download_file
 
       check_presence_and_length :file_reference, 33, FILE_REFERENCE_ERROR_MESSAGE
     end
 
+    # Checks that {Client#encryption_private_key} can be initialized properly. Is only run if
+    # {Client#bank} is `:danske` and {Client#command} is not `:create_certificate` or
+    # `:get_bank_certificate`.
     def check_encryption_private_key
       return unless bank == :danske
       return if [:create_certificate, :get_bank_certificate].include? command

data/lib/sepa/banks/danske/danske_response.rb

@@ -1,49 +1,90 @@
 module Sepa
+
+  # Handles Danske Bank specific {Response} functionality. Mainly decryption and certificate
+  # specific stuff.
   class DanskeResponse < Response
 
     validate :valid_get_bank_certificate_response
     validate :can_be_decrypted_with_given_key
 
+    # @return [String]
+    # @see Response#application_response
     def application_response
       @application_response ||= decrypt_application_response
     end
 
+    # Returns the bank's encryption certificate which is used to encrypt messages sent to the bank.
+    # The certificate is only present in `:get_bank_certificate` responess.
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:get_bank_certificate`
+    # @return [nil] if command is any other
     def bank_encryption_certificate
       return unless @command == :get_bank_certificate
 
       @bank_encryption_certificate ||= extract_cert(doc, 'BankEncryptionCert', DANSKE_PKI)
     end
 
+    # Returns the bank's signing certificate which is used by the bank to sign the responses. The
+    # certificate is only present in `:get_bank_certificate` responses
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:get_bank_certificate`
+    # @return [nil] if {#command} is any other
     def bank_signing_certificate
       return unless @command == :get_bank_certificate
 
       @bank_signing_certificate ||= extract_cert(doc, 'BankSigningCert', DANSKE_PKI)
     end
 
+    # Returns the bank's root certificate which is the certificate that is used to sign bank's other
+    # certificates. Only present in `:get_bank_certificate` responses.
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:get_bank_certificate`
+    # @return [nil] if {#command} is any other
     def bank_root_certificate
       return unless @command == :get_bank_certificate
 
       @bank_root_certificate ||= extract_cert(doc, 'BankRootCert', DANSKE_PKI)
     end
 
+    # Returns own encryption certificate which has been signed by the bank. Only present in
+    # `:create_certificate` responses
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:create_certificate`
+    # @return [nil] if command is any other
     def own_encryption_certificate
       return unless @command == :create_certificate
 
       @own_encryption_certificate ||= extract_cert(doc, 'EncryptionCert', DANSKE_PKI)
     end
 
+    # Returns own signing certificate which has been signed by the bank. Is used to sign requests
+    # sent to the bank. Is only present in `:create_certificate` responses.
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:create_certificate`
+    # @return [nil] if command is any other
     def own_signing_certificate
       return unless @command == :create_certificate
 
       @own_signing_certificate ||= extract_cert(doc, 'SigningCert', DANSKE_PKI)
     end
 
+    # Returns the CA certificate that has been used to sign own signing and encryption certificates.
+    # Only present in `:create_certificate` responses
+    #
+    # @return [OpenSSL::X509::Certificate] if {#command} is `:create_certificate`
+    # @return [nil] if command is any other
     def ca_certificate
       return unless @command == :create_certificate
 
       @ca_certificate ||= extract_cert(doc, 'CACert', DANSKE_PKI)
     end
 
+    # Extract certificate that has been used to sign the response. This overrides
+    # {Response#certificate} method with specific functionality for `:get_bank_certificate` and
+    # `:create_certificate` commands. Otherwise just calls {Response#certificate}
+    #
+    # @return [OpenSSL::X509::Certificate]
+    # @raise [OpenSSL::X509::CertificateError] if certificate cannot be processed
     def certificate
       if [:get_bank_certificate, :create_certificate].include? @command
         @certificate ||= begin
@@ -54,6 +95,13 @@ module Sepa
       end
     end
 
+    # Extract response code from the response. Overrides super method when {#command} is
+    # `:get_bank_certificate` or `:create_certificate` because response code node is named
+    # differently in those responses.
+    #
+    # @return [String] if response code is found
+    # @return [nil] if response code cannot be found
+    # @see Response#response_code
     def response_code
       return super unless [:get_bank_certificate, :create_certificate].include? @command
 
@@ -61,6 +109,12 @@ module Sepa
       node.content if node
     end
 
+    # Checks whether certificate embedded in the response has been signed with the bank's root
+    # certificate. Always returns true when {#command} is `:get_bank_certificate`, because the
+    # certificate is not present with that command.
+    #
+    # @return [true] if certificate is trusted
+    # @return [false] if certificate is not trusted
     def certificate_is_trusted?
       return true if @command == :get_bank_certificate
 
@@ -69,6 +123,14 @@ module Sepa
 
     private
 
+      # Finds a node by its reference URI from Danske Bank's certificate responses. If {#command} is
+      # other than `:get_bank_certificate` or `:create_certificate` returns super. This method is
+      # needed because Danske Bank uses a different way to reference nodes in their certificate
+      # responses.
+      #
+      # @param uri [String] reference URI of the node to find
+      # @return [Nokogiri::XML::Node] node with signature removed from its document since signature
+      #   has to be removed for canonicalization and hash calculation
       def find_node_by_uri(uri)
         return super unless [:get_bank_certificate, :create_certificate].include? @command
 
@@ -77,6 +139,15 @@ module Sepa
         doc_without_signature.at("[xml|id='#{uri}']")
       end
 
+      # Decrypts the application response in the response. Starts by calling {#decrypt_embedded_key}
+      # method to get the key used in encrypting the application response. After this the encrypted
+      # data is retrieved from the document and base64 decoded. After this the iv
+      # (initialization vector) is extracted from the encrypted data and a decipher with the
+      # 'DES-EDE3-CBC' algorithm is initialized (This is used by banks as encryption algorithm) and
+      # its key and iv set accordingly and mode changes to decrypt. After this the data is decrypted
+      # and returned as string.
+      #
+      # @return [String] the decrypted application response as raw xml
       def decrypt_application_response
         key = decrypt_embedded_key
 
@@ -96,6 +167,8 @@ module Sepa
         decipher.update(encypted_data) + decipher.final
       end
 
+      # Validates get bank certificate response. Response is valid if service fault is not returned
+      # from the bank.
       def valid_get_bank_certificate_response
         return unless @command == :get_bank_certificate
 
@@ -104,6 +177,11 @@ module Sepa
         end
       end
 
+      # Extracts the encrypted application response from the response and returns it as a nokogiri
+      # document
+      #
+      # @return [Nokogiri::XML] the encrypted application response if it is found
+      # @return [nil] if the application response cannot be found
       def encrypted_application_response
         @encrypted_application_response ||= begin
           encrypted_application_response = extract_application_response(BXD)
@@ -111,6 +189,8 @@ module Sepa
         end
       end
 
+      # Validates that the encrypted key in the response can be decrypted with the private key given
+      # to the response in the parameters. Response is invalid if this cannot be done.
       def can_be_decrypted_with_given_key
         return if [:get_bank_certificate, :create_certificate].include? @command
         return unless encrypted_application_response.css('CipherValue', 'xmlns' => XMLENC)[0]
@@ -120,6 +200,12 @@ module Sepa
         end
       end
 
+      # Decrypts (assymetrically) the symmetric encryption key embedded in the response with the
+      # private key given to the response in the parameters. The key is later used to decrypt the
+      # application response.
+      #
+      # @return [String] the encryption key as a string
+      # @return [nil] if the key cannot be decrypted with the given key
       def decrypt_embedded_key
         enc_key = encrypted_application_response.css('CipherValue', 'xmlns' => XMLENC)[0].content
         enc_key = decode enc_key