diaspora_federation 0.0.12 → 0.0.13

data/lib/diaspora_federation/salmon.rb

@@ -3,7 +3,7 @@ module DiasporaFederation
   # {http://www.salmon-protocol.org/ Salmon Protocol}.
   module Salmon
     # XML namespace url
-    XMLNS = "https://joindiaspora.com/protocol"
+    XMLNS = "https://joindiaspora.com/protocol".freeze
   end
 end
 
@@ -13,5 +13,6 @@ require "diaspora_federation/salmon/aes"
 require "diaspora_federation/salmon/exceptions"
 require "diaspora_federation/salmon/xml_payload"
 require "diaspora_federation/salmon/magic_envelope"
+require "diaspora_federation/salmon/encrypted_magic_envelope"
 require "diaspora_federation/salmon/slap"
 require "diaspora_federation/salmon/encrypted_slap"

data/lib/diaspora_federation/salmon/aes.rb

@@ -3,7 +3,7 @@ module DiasporaFederation
     # class for AES encryption and decryption
     class AES
       # OpenSSL aes cipher definition
-      CIPHER = "AES-256-CBC"
+      CIPHER = "AES-256-CBC".freeze
 
       # generates a random AES key and initialization vector
       # @return [Hash] { key: "...", iv: "..." }

data/lib/diaspora_federation/salmon/encrypted_magic_envelope.rb

@@ -0,0 +1,61 @@
+module DiasporaFederation
+  module Salmon
+    # This is a simple crypt-wrapper for {MagicEnvelope}.
+    #
+    # The wrapper is JSON with the following structure:
+    #
+    #   {
+    #     "aes_key": "...",
+    #     "encrypted_magic_envelope": "..."
+    #   }
+    #
+    # +aes_key+ is encrypted using the recipients public key, and contains the AES
+    # +key+ and +iv+ as JSON:
+    #
+    #   {
+    #     "key": "...",
+    #     "iv": "..."
+    #   }
+    #
+    # +encrypted_magic_envelope+ is encrypted using the +key+ and +iv+ from +aes_key+.
+    # Once decrypted it contains the {MagicEnvelope} xml:
+    #
+    #   <me:env>
+    #     ...
+    #   </me:env>
+    #
+    # All JSON-values (+aes_key+, +encrypted_magic_envelope+, +key+ and +iv+) are
+    # base64 encoded.
+    module EncryptedMagicEnvelope
+      # Generates a new random AES key and encrypts the {MagicEnvelope} with it.
+      # Then encrypts the AES key with the receivers public key.
+      # @param [Nokogiri::XML::Element] magic_env XML root node of a magic envelope
+      # @param [OpenSSL::PKey::RSA] pubkey recipient public_key
+      # @return [String] json string
+      def self.encrypt(magic_env, pubkey)
+        key = AES.generate_key_and_iv
+        encrypted_env = AES.encrypt(magic_env.to_xml, key[:key], key[:iv])
+
+        encoded_key = Hash[key.map {|k, v| [k, Base64.strict_encode64(v)] }]
+        encrypted_key = Base64.strict_encode64(pubkey.public_encrypt(JSON.generate(encoded_key)))
+
+        JSON.generate(aes_key: encrypted_key, encrypted_magic_envelope: encrypted_env)
+      end
+
+      # Decrypts the AES key with the private key of the receiver and decrypts the
+      # encrypted {MagicEnvelope} with it.
+      # @param [String] encrypted_env json string with aes_key and encrypted_magic_envelope
+      # @param [OpenSSL::PKey::RSA] privkey private key for decryption
+      # @return [Nokogiri::XML::Element] decrypted magic envelope xml
+      def self.decrypt(encrypted_env, privkey)
+        encrypted_json = JSON.parse(encrypted_env)
+
+        encoded_key = JSON.parse(privkey.private_decrypt(Base64.decode64(encrypted_json["aes_key"])))
+        key = Hash[encoded_key.map {|k, v| [k, Base64.decode64(v)] }]
+
+        xml = AES.decrypt(encrypted_json["encrypted_magic_envelope"], key["key"], key["iv"])
+        Nokogiri::XML::Document.parse(xml).root
+      end
+    end
+  end
+end

data/lib/diaspora_federation/salmon/encrypted_slap.rb

@@ -54,71 +54,94 @@ module DiasporaFederation
     #   recipient_pubkey = however_you_retrieve_the_recipients_public_key()
     #   entity = YourEntity.new(attr: "val")
     #
-    #   slap_xml = EncryptedSlap.generate_xml(author_id, author_privkey, entity, recipient_pubkey)
+    #   slap_xml = EncryptedSlap.prepare(author_id, author_privkey, entity).generate_xml(recipient_pubkey)
     #
     # @example Parsing a Salmon Slap
     #   recipient_privkey = however_you_retrieve_the_recipients_private_key()
-    #   slap = EncryptedSlap.from_xml(slap_xml, recipient_privkey)
-    #   author_pubkey = however_you_retrieve_the_authors_public_key(slap.author_id)
+    #   entity = EncryptedSlap.from_xml(slap_xml, recipient_privkey).payload
     #
-    #   entity = slap.entity(author_pubkey)
-    #
-    class EncryptedSlap
-      # Creates a Slap instance from the data within the given XML string
+    # @deprecated
+    class EncryptedSlap < Slap
+      # the author of the slap
+      # @param [String] value the author diaspora id
+      attr_writer :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
+
+      # the prepared encrypted magic envelope xml
+      # @param [Nokogiri::XML::Element] value magic envelope xml
+      attr_writer :magic_envelope_xml
+
+      # Creates a {MagicEnvelope} instance from the data within the given XML string
       # containing an encrypted payload.
       #
       # @param [String] slap_xml encrypted Salmon xml
-      # @param [OpenSSL::PKey::RSA] pkey recipient private_key for decryption
+      # @param [OpenSSL::PKey::RSA] privkey recipient private_key for decryption
       #
-      # @return [Slap] new Slap instance
+      # @return [MagicEnvelope] magic envelope instance with payload and sender
       #
       # @raise [ArgumentError] if any of the arguments is of the wrong type
       # @raise [MissingHeader] if the +encrypted_header+ element is missing in the XML
       # @raise [MissingMagicEnvelope] if the +me:env+ element is missing in the XML
-      def self.from_xml(slap_xml, pkey)
-        raise ArgumentError unless slap_xml.instance_of?(String) && pkey.instance_of?(OpenSSL::PKey::RSA)
+      def self.from_xml(slap_xml, privkey)
+        raise ArgumentError unless slap_xml.instance_of?(String) && privkey.instance_of?(OpenSSL::PKey::RSA)
         doc = Nokogiri::XML::Document.parse(slap_xml)
 
-        Slap.new.tap do |slap|
-          header_elem = doc.at_xpath("d:diaspora/d:encrypted_header", Slap::NS)
-          raise MissingHeader if header_elem.nil?
-          header = header_data(header_elem.content, pkey)
-          slap.author_id = header[:author_id]
-          slap.cipher_params = {key: Base64.decode64(header[:aes_key]), iv: Base64.decode64(header[:iv])}
+        header_elem = doc.at_xpath("d:diaspora/d:encrypted_header", Slap::NS)
+        raise MissingHeader if header_elem.nil?
+        header = header_data(header_elem.content, privkey)
+        sender = header[:author_id]
+        cipher_params = {key: Base64.decode64(header[:aes_key]), iv: Base64.decode64(header[:iv])}
 
-          slap.add_magic_env_from_doc(doc)
-        end
+        MagicEnvelope.unenvelop(magic_env_from_doc(doc), sender, cipher_params)
       end
 
-      # Creates an encrypted Salmon Slap and returns the XML string.
+      # Creates an encrypted Salmon Slap.
       #
       # @param [String] author_id Diaspora* handle of the author
-      # @param [OpenSSL::PKey::RSA] pkey sender private key for signing the magic envelope
+      # @param [OpenSSL::PKey::RSA] privkey sender private key for signing the magic envelope
       # @param [Entity] entity payload
+      # @return [EncryptedSlap] encrypted Slap instance
+      # @raise [ArgumentError] if any of the arguments is of the wrong type
+      def self.prepare(author_id, privkey, entity)
+        raise ArgumentError unless author_id.instance_of?(String) &&
+                                   privkey.instance_of?(OpenSSL::PKey::RSA) &&
+                                   entity.is_a?(Entity)
+
+        EncryptedSlap.new.tap do |slap|
+          slap.author_id = author_id
+
+          magic_envelope = MagicEnvelope.new(entity)
+          slap.cipher_params = magic_envelope.encrypt!
+          slap.magic_envelope_xml = magic_envelope.envelop(privkey)
+        end
+      end
+
+      # Creates an encrypted Salmon Slap XML string.
+      #
       # @param [OpenSSL::PKey::RSA] pubkey recipient public key for encrypting the AES key
       # @return [String] Salmon XML string
       # @raise [ArgumentError] if any of the arguments is of the wrong type
-      def self.generate_xml(author_id, pkey, entity, pubkey)
-        raise ArgumentError unless author_id.instance_of?(String) &&
-                                   pkey.instance_of?(OpenSSL::PKey::RSA) &&
-                                   entity.is_a?(Entity) &&
-                                   pubkey.instance_of?(OpenSSL::PKey::RSA)
+      def generate_xml(pubkey)
+        raise ArgumentError unless pubkey.instance_of?(OpenSSL::PKey::RSA)
 
         Slap.build_xml do |xml|
-          magic_envelope = MagicEnvelope.new(pkey, entity)
-          envelope_key = magic_envelope.encrypt!
+          xml.encrypted_header(encrypted_header(@author_id, @cipher_params, pubkey))
 
-          encrypted_header(author_id, envelope_key, pubkey, xml)
-          magic_envelope.envelop(xml)
+          xml.parent << @magic_envelope_xml
         end
       end
 
+      private
+
       # decrypts and reads the data from the encrypted XML header
       # @param [String] data base64 encoded, encrypted header data
-      # @param [OpenSSL::PKey::RSA] pkey private key for decryption
+      # @param [OpenSSL::PKey::RSA] privkey private key for decryption
       # @return [Hash] { iv: "...", aes_key: "...", author_id: "..." }
-      def self.header_data(data, pkey)
-        header_elem = decrypt_header(data, pkey)
+      def self.header_data(data, privkey)
+        header_elem = decrypt_header(data, privkey)
         raise InvalidHeader unless header_elem.name == "decrypted_header"
 
         iv = header_elem.at_xpath("iv").content
@@ -131,11 +154,11 @@ module DiasporaFederation
 
       # decrypts the xml header
       # @param [String] data base64 encoded, encrypted header data
-      # @param [OpenSSL::PKey::RSA] pkey private key for decryption
+      # @param [OpenSSL::PKey::RSA] privkey private key for decryption
       # @return [Nokogiri::XML::Element] header xml document
-      def self.decrypt_header(data, pkey)
+      def self.decrypt_header(data, privkey)
         cipher_header = JSON.parse(Base64.decode64(data))
-        key = JSON.parse(pkey.private_decrypt(Base64.decode64(cipher_header["aes_key"])))
+        key = JSON.parse(privkey.private_decrypt(Base64.decode64(cipher_header["aes_key"])))
 
         xml = AES.decrypt(cipher_header["ciphertext"], Base64.decode64(key["key"]), Base64.decode64(key["iv"]))
         Nokogiri::XML::Document.parse(xml).root
@@ -147,43 +170,39 @@ module DiasporaFederation
       # @param [String] author_id diaspora_handle
       # @param [Hash] envelope_key envelope cipher params
       # @param [OpenSSL::PKey::RSA] pubkey recipient public_key
-      # @param [Nokogiri::XML::Element] xml parent element for inserting in XML document
-      def self.encrypted_header(author_id, envelope_key, pubkey, xml)
+      # @return [String] encrypted base64 encoded header
+      def encrypted_header(author_id, envelope_key, pubkey)
         data = header_xml(author_id, strict_base64_encode(envelope_key))
-        key = AES.generate_key_and_iv
-        ciphertext = AES.encrypt(data, key[:key], key[:iv])
+        header_key = AES.generate_key_and_iv
+        ciphertext = AES.encrypt(data, header_key[:key], header_key[:iv])
 
-        json_key = JSON.generate(strict_base64_encode(key))
+        json_key = JSON.generate(strict_base64_encode(header_key))
         encrypted_key = Base64.strict_encode64(pubkey.public_encrypt(json_key))
 
         json_header = JSON.generate(aes_key: encrypted_key, ciphertext: ciphertext)
 
-        xml.encrypted_header(Base64.strict_encode64(json_header))
+        Base64.strict_encode64(json_header)
       end
-      private_class_method :encrypted_header
 
       # generate the header xml string, including the author, aes_key and iv
       # @param [String] author_id diaspora_handle of the author
       # @param [Hash] envelope_key { key: "...", iv: "..." } (values in base64)
       # @return [String] header XML string
-      def self.header_xml(author_id, envelope_key)
-        builder = Nokogiri::XML::Builder.new do |xml|
+      def header_xml(author_id, envelope_key)
+        @header_xml ||= Nokogiri::XML::Builder.new(encoding: "UTF-8") {|xml|
           xml.decrypted_header {
             xml.iv(envelope_key[:iv])
             xml.aes_key(envelope_key[:key])
             xml.author_id(author_id)
           }
-        end
-        builder.to_xml.strip
+        }.to_xml.strip
       end
-      private_class_method :header_xml
 
       # @param [Hash] hash { key: "...", iv: "..." }
       # @return [Hash] encoded hash: { key: "...", iv: "..." }
-      def self.strict_base64_encode(hash)
+      def strict_base64_encode(hash)
         Hash[hash.map {|k, v| [k, Base64.strict_encode64(v)] }]
       end
-      private_class_method :strict_base64_encode
     end
   end
 end

data/lib/diaspora_federation/salmon/exceptions.rb

@@ -1,21 +1,29 @@
 module DiasporaFederation
   module Salmon
     # Raised, if the element containing the Magic Envelope is missing from the XML
+    # @deprecated
     class MissingMagicEnvelope < RuntimeError
     end
 
     # Raised, if the element containing the author is empty.
+    # @deprecated
     class MissingAuthor < RuntimeError
     end
 
     # Raised, if the element containing the header is missing from the XML
+    # @deprecated
     class MissingHeader < RuntimeError
     end
 
     # Raised if the decrypted header has an unexpected XML structure
+    # @deprecated
     class InvalidHeader < RuntimeError
     end
 
+    # Raised, if failed to fetch the public key of the sender of the received message
+    class SenderKeyNotFound < RuntimeError
+    end
+
     # Raised, if the Magic Envelope XML structure is malformed.
     class InvalidEnvelope < RuntimeError
     end
@@ -32,19 +40,5 @@ module DiasporaFederation
     # Raised, if the parsed Magic Envelope specifies an unhandled encoding.
     class InvalidEncoding < RuntimeError
     end
-
-    # Raised, if the XML structure of the parsed document doesn't resemble the
-    # expected structure.
-    class InvalidStructure < RuntimeError
-    end
-
-    # Raised, if the entity name in the XML is invalid
-    class InvalidEntityName < RuntimeError
-    end
-
-    # Raised, if the entity contained within the XML cannot be mapped to a
-    # defined {Entity} subclass.
-    class UnknownEntity < RuntimeError
-    end
   end
 end

data/lib/diaspora_federation/salmon/magic_envelope.rb

@@ -13,7 +13,7 @@ module DiasporaFederation
     #     <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:sig key_id="{sender}">{signature}</me:sig>
     #   </me:env>
     #
     # When parsing the XML of an incoming Magic Envelope {MagicEnvelope.unenvelop}
@@ -21,47 +21,56 @@ module DiasporaFederation
     #
     # @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"
+      ENCODING = "base64url".freeze
 
       # algorithm used for signing the payload data
-      ALGORITHM = "RSA-SHA256"
+      ALGORITHM = "RSA-SHA256".freeze
 
       # mime type describing the payload data
-      DATA_TYPE = "application/xml"
+      DATA_TYPE = "application/xml".freeze
 
       # digest instance used for signing
       DIGEST = OpenSSL::Digest::SHA256.new
 
       # XML namespace url
-      XMLNS = "http://salmon-protocol.org/ns/magic-env"
+      XMLNS = "http://salmon-protocol.org/ns/magic-env".freeze
+
+      # the payload entity of the magic envelope
+      # @return [Entity] payload entity
+      attr_reader :payload
+
+      # the sender of the magic envelope
+      # @return [String] diaspora-ID of the sender
+      attr_reader :sender
 
       # Creates a new instance of MagicEnvelope.
       #
-      # @param [OpenSSL::PKey::RSA] rsa_pkey private key used for signing
       # @param [Entity] payload Entity instance
+      # @param [String] sender diaspora-ID of the sender
       # @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)
+      def initialize(payload, sender=nil)
+        raise ArgumentError unless payload.is_a?(Entity)
 
-        @rsa_pkey = rsa_pkey
-        @payload = XmlPayload.pack(payload).to_xml.strip
+        @payload = payload
+        @sender = sender
       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))
+      # @param [OpenSSL::PKey::RSA] privkey private key used for signing
+      # @return [Nokogiri::XML::Element] XML root node
+      def envelop(privkey)
+        raise ArgumentError unless privkey.instance_of?(OpenSSL::PKey::RSA)
+
+        build_xml {|xml|
+          xml["me"].env("xmlns:me" => XMLNS) {
+            xml["me"].data(Base64.urlsafe_encode64(payload_data), type: DATA_TYPE)
+            xml["me"].encoding(ENCODING)
+            xml["me"].alg(ALGORITHM)
+            xml["me"].sig(Base64.urlsafe_encode64(sign(privkey)), key_id)
+          }
         }
       end
 
@@ -77,7 +86,7 @@ module DiasporaFederation
       # @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])
+          @payload_data = AES.encrypt(payload_data, key[:key], key[:iv])
         end
       end
 
@@ -90,7 +99,7 @@ module DiasporaFederation
       # @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 [String] sender diaspora-ID of the sender or nil
       # @param [Hash] cipher_params hash containing the key and iv for
       #   AES-decrypting previously encrypted data. E.g.: { iv: "...", key: "..." }
       #
@@ -101,32 +110,52 @@ module DiasporaFederation
       # @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)
+      def self.unenvelop(magic_env, sender=nil, cipher_params=nil)
+        raise ArgumentError unless magic_env.instance_of?(Nokogiri::XML::Element)
 
         raise InvalidEnvelope unless envelope_valid?(magic_env)
-        raise InvalidSignature unless signature_valid?(magic_env, rsa_pubkey)
+
+        sender ||= sender(magic_env)
+        raise InvalidSignature unless signature_valid?(magic_env, sender)
 
         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)
+        new(XmlPayload.unpack(Nokogiri::XML::Document.parse(data).root), sender)
       end
 
       private
 
+      # the payload data as string
+      # @return [String] payload data
+      def payload_data
+        @payload_data ||= XmlPayload.pack(@payload).to_xml.strip
+      end
+
+      def key_id
+        sender ? {key_id: Base64.urlsafe_encode64(sender)} : {}
+      end
+
+      # Builds the xml root node of the magic envelope.
+      #
+      # @yield [xml] Invokes the block with the
+      #   {http://www.rubydoc.info/gems/nokogiri/Nokogiri/XML/Builder Nokogiri::XML::Builder}
+      # @return [Nokogiri::XML::Element] XML root node
+      def build_xml
+        Nokogiri::XML::Builder.new(encoding: "UTF-8") {|xml|
+          yield xml
+        }.doc.root
+      end
+
       # create the signature for all fields according to specification
       #
+      # @param [OpenSSL::PKey::RSA] privkey private key used for signing
       # @return [String] the signature
-      def signature
-        subject = self.class.sig_subject([@payload,
-                                          DATA_TYPE,
-                                          ENCODING,
-                                          ALGORITHM])
-        @rsa_pkey.sign(DIGEST, subject)
+      def sign(privkey)
+        subject = MagicEnvelope.send(:sig_subject, [payload_data, DATA_TYPE, ENCODING, ALGORITHM])
+        privkey.sign(DIGEST, subject)
       end
 
       # @param [Nokogiri::XML::Element] env magic envelope XML
@@ -134,26 +163,37 @@ module DiasporaFederation
         (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
+      # @param [String] sender diaspora-ID of the sender or nil
       # @return [Boolean]
-      def self.signature_valid?(env, pkey)
+      def self.signature_valid?(env, sender)
         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])
 
+        sender_key = DiasporaFederation.callbacks.trigger(:fetch_public_key_by_diaspora_id, sender)
+        raise SenderKeyNotFound unless sender_key
+
         sig = Base64.urlsafe_decode64(env.at_xpath("me:sig").content)
-        pkey.verify(DIGEST, sig, subject)
+        sender_key.verify(DIGEST, sig, subject)
       end
       private_class_method :signature_valid?
 
+      # reads the +key_id+ from the magic envelope
+      # @param [Nokogiri::XML::Element] env magic envelope XML
+      # @return [String] diaspora-ID of the sender
+      def self.sender(env)
+        key_id = env.at_xpath("me:sig")["key_id"]
+        raise InvalidEnvelope, "no key_id" unless key_id # TODO: move to `envelope_valid?`
+        Base64.urlsafe_decode64(key_id)
+      end
+      private_class_method :sender
+
       # constructs the signature subject.
       # the given array should consist of the data, data_type (mimetype), encoding
       # and the algorithm
@@ -162,6 +202,7 @@ module DiasporaFederation
       def self.sig_subject(data_arr)
         data_arr.map {|i| Base64.urlsafe_encode64(i) }.join(".")
       end
+      private_class_method :sig_subject
 
       # @param [Nokogiri::XML::Element] magic_env magic envelope XML
       # @return [Boolean]