diaspora_federation 0.0.8 → 0.0.9

data/lib/diaspora_federation/salmon/magic_envelope.rb

@@ -0,0 +1,191 @@
+module DiasporaFederation
+  module Salmon
+    # Represents a Magic Envelope for Diaspora* federation messages.
+    #
+    # When generating a Magic Envelope, an instance of this class is created and
+    # the contents are specified on initialization. Optionally, the payload can be
+    # encrypted ({MagicEnvelope#encrypt!}), before the XML is returned
+    # ({MagicEnvelope#envelop}).
+    #
+    # The generated XML appears like so:
+    #
+    #   <me:env>
+    #     <me:data type="application/xml">{data}</me:data>
+    #     <me:encoding>base64url</me:encoding>
+    #     <me:alg>RSA-SHA256</me:alg>
+    #     <me:sig>{signature}</me:sig>
+    #   </me:env>
+    #
+    # When parsing the XML of an incoming Magic Envelope {MagicEnvelope.unenvelop}
+    # is used.
+    #
+    # @see http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html
+    class MagicEnvelope
+      # returns the payload (only used for testing purposes)
+      attr_reader :payload
+
+      # encoding used for the payload data
+      ENCODING = "base64url"
+
+      # algorithm used for signing the payload data
+      ALGORITHM = "RSA-SHA256"
+
+      # mime type describing the payload data
+      DATA_TYPE = "application/xml"
+
+      # digest instance used for signing
+      DIGEST = OpenSSL::Digest::SHA256.new
+
+      # XML namespace url
+      XMLNS = "http://salmon-protocol.org/ns/magic-env"
+
+      # Creates a new instance of MagicEnvelope.
+      #
+      # @param [OpenSSL::PKey::RSA] rsa_pkey private key used for signing
+      # @param [Entity] payload Entity instance
+      # @raise [ArgumentError] if either argument is not of the right type
+      def initialize(rsa_pkey, payload)
+        raise ArgumentError unless rsa_pkey.instance_of?(OpenSSL::PKey::RSA) &&
+                                   payload.is_a?(Entity)
+
+        @rsa_pkey = rsa_pkey
+        @payload = XmlPayload.pack(payload).to_xml.strip
+      end
+
+      # Builds the XML structure for the magic envelope, inserts the {ENCODING}
+      # encoded data and signs the envelope using {DIGEST}.
+      #
+      # @param [Nokogiri::XML::Builder] xml Salmon XML builder
+      def envelop(xml)
+        xml["me"].env {
+          xml["me"].data(Base64.urlsafe_encode64(@payload), type: DATA_TYPE)
+          xml["me"].encoding(ENCODING)
+          xml["me"].alg(ALGORITHM)
+          xml["me"].sig(Base64.urlsafe_encode64(signature))
+        }
+      end
+
+      # Encrypts the payload with a new, random AES cipher and returns the cipher
+      # params that were used.
+      #
+      # This must happen after the MagicEnvelope instance was created and before
+      # {MagicEnvelope#envelop} is called.
+      #
+      # @see AES#generate_key_and_iv
+      # @see AES#encrypt
+      #
+      # @return [Hash] AES key and iv. E.g.: { key: "...", iv: "..." }
+      def encrypt!
+        AES.generate_key_and_iv.tap do |key|
+          @payload = AES.encrypt(@payload, key[:key], key[:iv])
+        end
+      end
+
+      # Extracts the entity encoded in the magic envelope data, if the signature
+      # is valid. If +cipher_params+ is given, also attempts to decrypt the payload first.
+      #
+      # Does some sanity checking to avoid bad surprises...
+      #
+      # @see XmlPayload#unpack
+      # @see AES#decrypt
+      #
+      # @param [Nokogiri::XML::Element] magic_env XML root node of a magic envelope
+      # @param [OpenSSL::PKey::RSA] rsa_pubkey public key to verify the signature
+      # @param [Hash] cipher_params hash containing the key and iv for
+      #   AES-decrypting previously encrypted data. E.g.: { iv: "...", key: "..." }
+      #
+      # @return [Entity] reconstructed entity instance
+      #
+      # @raise [ArgumentError] if any of the arguments is of invalid type
+      # @raise [InvalidEnvelope] if the envelope XML structure is malformed
+      # @raise [InvalidSignature] if the signature can't be verified
+      # @raise [InvalidEncoding] if the data is wrongly encoded
+      # @raise [InvalidAlgorithm] if the algorithm used doesn't match
+      def self.unenvelop(magic_env, rsa_pubkey, cipher_params=nil)
+        raise ArgumentError unless rsa_pubkey.instance_of?(OpenSSL::PKey::RSA) &&
+                                   magic_env.instance_of?(Nokogiri::XML::Element)
+
+        raise InvalidEnvelope unless envelope_valid?(magic_env)
+        raise InvalidSignature unless signature_valid?(magic_env, rsa_pubkey)
+
+        raise InvalidEncoding unless encoding_valid?(magic_env)
+        raise InvalidAlgorithm unless algorithm_valid?(magic_env)
+
+        data = read_and_decrypt_data(magic_env, cipher_params)
+
+        XmlPayload.unpack(Nokogiri::XML::Document.parse(data).root)
+      end
+
+      private
+
+      # create the signature for all fields according to specification
+      #
+      # @return [String] the signature
+      def signature
+        subject = self.class.sig_subject([@payload,
+                                          DATA_TYPE,
+                                          ENCODING,
+                                          ALGORITHM])
+        @rsa_pkey.sign(DIGEST, subject)
+      end
+
+      # @param [Nokogiri::XML::Element] env magic envelope XML
+      def self.envelope_valid?(env)
+        (env.instance_of?(Nokogiri::XML::Element) &&
+          env.name == "env" &&
+          !env.at_xpath("me:data").content.empty? &&
+          !env.at_xpath("me:encoding").content.empty? &&
+          !env.at_xpath("me:alg").content.empty? &&
+          !env.at_xpath("me:sig").content.empty?)
+      end
+      private_class_method :envelope_valid?
+
+      # @param [Nokogiri::XML::Element] env magic envelope XML
+      # @param [OpenSSL::PKey::RSA] pkey public key
+      # @return [Boolean]
+      def self.signature_valid?(env, pkey)
+        subject = sig_subject([Base64.urlsafe_decode64(env.at_xpath("me:data").content),
+                               env.at_xpath("me:data")["type"],
+                               env.at_xpath("me:encoding").content,
+                               env.at_xpath("me:alg").content])
+
+        sig = Base64.urlsafe_decode64(env.at_xpath("me:sig").content)
+        pkey.verify(DIGEST, sig, subject)
+      end
+      private_class_method :signature_valid?
+
+      # constructs the signature subject.
+      # the given array should consist of the data, data_type (mimetype), encoding
+      # and the algorithm
+      # @param [Array<String>] data_arr
+      # @return [String] signature subject
+      def self.sig_subject(data_arr)
+        data_arr.map {|i| Base64.urlsafe_encode64(i) }.join(".")
+      end
+
+      # @param [Nokogiri::XML::Element] magic_env magic envelope XML
+      # @return [Boolean]
+      def self.encoding_valid?(magic_env)
+        magic_env.at_xpath("me:encoding").content == ENCODING
+      end
+      private_class_method :encoding_valid?
+
+      # @param [Nokogiri::XML::Element] magic_env magic envelope XML
+      # @return [Boolean]
+      def self.algorithm_valid?(magic_env)
+        magic_env.at_xpath("me:alg").content == ALGORITHM
+      end
+      private_class_method :algorithm_valid?
+
+      # @param [Nokogiri::XML::Element] magic_env magic envelope XML
+      # @param [Hash] cipher_params hash containing the key and iv
+      # @return [String] data
+      def self.read_and_decrypt_data(magic_env, cipher_params)
+        data = Base64.urlsafe_decode64(magic_env.at_xpath("me:data").content)
+        data = AES.decrypt(data, cipher_params[:key], cipher_params[:iv]) unless cipher_params.nil?
+        data
+      end
+      private_class_method :read_and_decrypt_data
+    end
+  end
+end

data/lib/diaspora_federation/salmon/slap.rb

@@ -0,0 +1,128 @@
+module DiasporaFederation
+  module Salmon
+    # +Slap+ provides class methods to create unencrypted Slap XML from payload
+    # data and parse incoming XML into a Slap instance.
+    #
+    # A Diaspora*-flavored magic-enveloped XML message looks like the following:
+    #
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <diaspora xmlns="https://joindiaspora.com/protocol" xmlns:me="http://salmon-protocol.org/ns/magic-env">
+    #     <header>
+    #       <author_id>{author}</author_id>
+    #     </header>
+    #     {magic_envelope}
+    #   </diaspora>
+    #
+    # @example Generating a Salmon Slap
+    #   author_id = "author@pod.example.tld"
+    #   author_privkey = however_you_retrieve_the_authors_private_key(author_id)
+    #   entity = YourEntity.new(attr: "val")
+    #
+    #   slap_xml = Slap.generate_xml(author_id, author_privkey, entity)
+    #
+    # @example Parsing a Salmon Slap
+    #   slap = Slap.from_xml(slap_xml)
+    #   author_pubkey = however_you_retrieve_the_authors_public_key(slap.author_id)
+    #
+    #   entity = slap.entity(author_pubkey)
+    class Slap
+      # the author of the slap
+      # @overload author_id
+      #   @return [String] the author diaspora id
+      # @overload author_id=
+      #   @param [String] the author diaspora id
+      attr_accessor :author_id
+
+      # the key and iv if it is an encrypted slap
+      # @param [Hash] value hash containing the key and iv
+      attr_writer :cipher_params
+
+      # Namespaces
+      NS = {d: Salmon::XMLNS, me: MagicEnvelope::XMLNS}
+
+      # Returns new instance of the Entity that is contained within the XML of
+      # this Slap.
+      #
+      # The first time this is called, a public key has to be specified to verify
+      # the Magic Envelope signature. On repeated calls, the key may be omitted.
+      #
+      # @see MagicEnvelope.unenvelop
+      #
+      # @param [OpenSSL::PKey::RSA] pubkey public key for validating the signature
+      # @return [Entity] entity instance from the XML
+      # @raise [ArgumentError] if the public key is of the wrong type
+      def entity(pubkey=nil)
+        return @entity unless @entity.nil?
+
+        raise ArgumentError unless pubkey.instance_of?(OpenSSL::PKey::RSA)
+        @entity = MagicEnvelope.unenvelop(@magic_envelope, pubkey, @cipher_params)
+        @entity
+      end
+
+      # Parses an unencrypted Salmon XML string and returns a new instance of
+      # {Slap} populated with the XML data.
+      #
+      # @param [String] slap_xml Salmon XML
+      # @return [Slap] new Slap instance
+      # @raise [ArgumentError] if the argument is not a String
+      # @raise [MissingAuthor] if the +author_id+ element is missing from the XML
+      # @raise [MissingMagicEnvelope] if the +me:env+ element is missing from the XML
+      def self.from_xml(slap_xml)
+        raise ArgumentError unless slap_xml.instance_of?(String)
+        doc = Nokogiri::XML::Document.parse(slap_xml)
+
+        Slap.new.tap do |slap|
+          author_elem = doc.at_xpath("d:diaspora/d:header/d:author_id", Slap::NS)
+          raise MissingAuthor if author_elem.nil? || author_elem.content.empty?
+          slap.author_id = author_elem.content
+
+          slap.add_magic_env_from_doc(doc)
+        end
+      end
+
+      # Creates an unencrypted Salmon Slap and returns the XML string.
+      #
+      # @param [String] author_id Diaspora* handle of the author
+      # @param [OpenSSL::PKey::RSA] pkey sender private_key for signing the magic envelope
+      # @param [Entity] entity payload
+      # @return [String] Salmon XML string
+      # @raise [ArgumentError] if any of the arguments is not the correct type
+      def self.generate_xml(author_id, pkey, entity)
+        raise ArgumentError unless author_id.instance_of?(String) &&
+                                   pkey.instance_of?(OpenSSL::PKey::RSA) &&
+                                   entity.is_a?(Entity)
+
+        build_xml do |xml|
+          xml.header {
+            xml.author_id(author_id)
+          }
+
+          MagicEnvelope.new(pkey, entity).envelop(xml)
+        end
+      end
+
+      # Builds the xml for the Salmon Slap.
+      #
+      # @yield [xml] Invokes the block with the
+      #   {http://www.rubydoc.info/gems/nokogiri/Nokogiri/XML/Builder Nokogiri::XML::Builder}
+      # @return [String] Slap XML
+      def self.build_xml
+        builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+          xml.diaspora("xmlns" => Salmon::XMLNS, "xmlns:me" => MagicEnvelope::XMLNS) {
+            yield xml
+          }
+        end
+        builder.to_xml
+      end
+
+      # Parses the magic envelop from the document.
+      #
+      # @param [Nokogiri::XML::Document] doc Salmon XML Document
+      def add_magic_env_from_doc(doc)
+        @magic_envelope = doc.at_xpath("d:diaspora/me:env", Slap::NS).tap do |env|
+          raise MissingMagicEnvelope if env.nil?
+        end
+      end
+    end
+  end
+end

data/lib/diaspora_federation/salmon/xml_payload.rb

@@ -0,0 +1,158 @@
+module DiasporaFederation
+  module Salmon
+    # +XmlPayload+ provides methods to wrap a XML-serialized {Entity} inside a
+    # common XML structure that will become the payload for federation messages.
+    #
+    # The wrapper looks like so:
+    #   <XML>
+    #     <post>
+    #       {data}
+    #     </post>
+    #   </XML>
+    #
+    # (The +post+ element is there for historic reasons...)
+    module XmlPayload
+      # Encapsulates an Entity inside the wrapping xml structure
+      # and returns the XML Object.
+      #
+      # @param [Entity] entity subject
+      # @return [Nokogiri::XML::Element] XML root node
+      # @raise [ArgumentError] if the argument is not an Entity subclass
+      def self.pack(entity)
+        raise ArgumentError, "only instances of DiasporaFederation::Entity allowed" unless entity.is_a?(Entity)
+
+        entity_xml = entity.to_xml
+        doc = entity_xml.document
+        wrap = Nokogiri::XML::Element.new("XML", doc)
+        wrap_post = Nokogiri::XML::Element.new("post", doc)
+        entity_xml.parent = wrap_post
+        wrap << wrap_post
+
+        wrap
+      end
+
+      # Extracts the Entity XML from the wrapping XML structure, parses the entity
+      # XML and returns a new instance of the Entity that was packed inside the
+      # given payload.
+      #
+      # @param [Nokogiri::XML::Element] xml payload XML root node
+      # @return [Entity] re-constructed Entity instance
+      # @raise [ArgumentError] if the argument is not an
+      #   {http://www.rubydoc.info/gems/nokogiri/Nokogiri/XML/Element Nokogiri::XML::Element}
+      # @raise [InvalidStructure] if the XML doesn't look like the wrapper XML
+      # @raise [UnknownEntity] if the class for the entity contained inside the
+      #   XML can't be found
+      def self.unpack(xml)
+        raise ArgumentError, "only Nokogiri::XML::Element allowed" unless xml.instance_of?(Nokogiri::XML::Element)
+        raise Salmon::InvalidStructure unless wrap_valid?(xml)
+
+        data = xml.at_xpath("post/*[1]")
+        klass_name = entity_class_name(data.name)
+        raise Salmon::UnknownEntity, "'#{klass_name}' not found" unless Entities.const_defined?(klass_name)
+
+        klass = Entities.const_get(klass_name)
+        populate_entity(klass, data)
+      end
+
+      private
+
+      # @param [Nokogiri::XML::Element] element
+      def self.wrap_valid?(element)
+        (element.name == "XML" && !element.at_xpath("post").nil? &&
+         !element.at_xpath("post").children.empty?)
+      end
+      private_class_method :wrap_valid?
+
+      # Transform the given String from the lowercase underscored version to a
+      # camelized variant, used later for getting the Class constant.
+      #
+      # @param [String] term "snake_case" class name
+      # @return [String] "CamelCase" class name
+      def self.entity_class_name(term)
+        term.to_s.tap do |string|
+          raise Salmon::InvalidEntityName, "'#{string}' is invalid" unless string =~ /^[a-z]*(_[a-z]*)*$/
+          string.sub!(/^[a-z]/, &:upcase)
+          string.gsub!(/_([a-z])/) { Regexp.last_match[1].upcase }
+        end
+      end
+      private_class_method :entity_class_name
+
+      # Construct a new instance of the given Entity and populate the properties
+      # with the attributes found in the XML.
+      # Works recursively on nested Entities and Arrays thereof.
+      #
+      # @param [Class] klass entity class
+      # @param [Nokogiri::XML::Element] root_node xml nodes
+      # @return [Entity] instance
+      def self.populate_entity(klass, root_node)
+        # Use all known properties to build the Entity. All other elements are respected
+        # and attached to resulted hash as string. It is intended to build a hash
+        # invariable of an Entity definition, in order to support receiving objects
+        # from the future versions of Diaspora, where new elements may have been added.
+        data = Hash[root_node.element_children.map { |child|
+          xml_name = child.name
+          property = klass.class_props.find {|prop| prop[:xml_name].to_s == xml_name }
+          if property
+            parse_element_from_node(property[:name], property[:type], xml_name, root_node)
+          else
+            [xml_name, child.text]
+          end
+        }]
+
+        Entities::Relayable.verify_signatures(data) if klass.included_modules.include?(Entities::Relayable)
+
+        klass.new(data)
+      end
+      private_class_method :populate_entity
+
+      # @param [Symbol] name property name
+      # @param [Class] type target type to parse
+      # @param [String] xml_name xml tag to parse
+      # @param [Nokogiri::XML::Element] node XML node to parse
+      # @return [Array<Symbol, Object>] parsed data
+      def self.parse_element_from_node(name, type, xml_name, node)
+        if type == String
+          [name, parse_string_from_node(xml_name, node)]
+        elsif type.instance_of?(Array)
+          [name, parse_array_from_node(type, node)]
+        elsif type.ancestors.include?(Entity)
+          [name, parse_entity_from_node(type, node)]
+        end
+      end
+      private_class_method :parse_element_from_node
+
+      # create simple entry in data hash
+      #
+      # @param [String] name xml tag to parse
+      # @param [Nokogiri::XML::Element] root_node XML root_node to parse
+      # @return [String] data
+      def self.parse_string_from_node(name, root_node)
+        node = root_node.xpath(name.to_s)
+        node.first.text if node.any?
+      end
+      private_class_method :parse_string_from_node
+
+      # create an entry in the data hash for the nested entity
+      #
+      # @param [Class] type target type to parse
+      # @param [Nokogiri::XML::Element] root_node XML node to parse
+      # @return [Entity] parsed child entity
+      def self.parse_entity_from_node(type, root_node)
+        node = root_node.xpath(type.entity_name)
+        populate_entity(type, node.first) if node.any?
+      end
+      private_class_method :parse_entity_from_node
+
+      # collect all nested children of that type and create an array in the data hash
+      #
+      # @param [Array<Class>] type target type to parse
+      # @param [Nokogiri::XML::Element] root_node XML node to parse
+      # @return [Array<Entity>] array with parsed child entities
+      def self.parse_array_from_node(type, root_node)
+        node = root_node.xpath(type.first.entity_name)
+        node.map {|child| populate_entity(type.first, child) }
+      end
+      private_class_method :parse_array_from_node
+    end
+  end
+end