ronin-support 0.5.2 → 1.0.0.beta2

data/lib/ronin/support/network/smtp/email.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Support
+    module Network
+      module SMTP
+        #
+        # Represents an Email to be sent over {SMTP}.
+        #
+        class Email
+
+          # The CR-LF String
+          CRLF = "\n\r"
+
+          # Sender of the email
+          #
+          # @return [String]
+          attr_accessor :from
+
+          # Recipient of the email
+          #
+          # @return [Array<#to_s>, String]
+          attr_accessor :to
+
+          # Subject of the email
+          #
+          # @return [String]
+          attr_accessor :subject
+
+          # Date of the email
+          #
+          # @return [String, Time]
+          attr_accessor :date
+
+          # Unique message-id string
+          #
+          # @return [String]
+          attr_accessor :message_id
+
+          # Additional headers
+          #
+          # @return [Hash{String => String}]
+          attr_reader :headers
+
+          # Body of the email
+          #
+          # @return [String, Array<String>]
+          attr_accessor :body
+
+          #
+          # Creates a new Email object.
+          #
+          # @param [String] from
+          #   The address the email is from.
+          #
+          # @param [Array<#to_s>, String] to
+          #   The address that the email should be sent to.
+          #
+          # @param [String] subject
+          #   The subject of the email.
+          #
+          # @param [String] message_id
+          #   Message-ID of the email.
+          #
+          # @param [String, Time] date
+          #   The date the email was sent on.
+          #
+          # @param [Hash<String => String}] headers
+          #   Additional headers.
+          #
+          # @param [String, Array<String>] body
+          #   The body of the email.
+          #
+          # @yield [email]
+          #   If a block is given, it will be passed the newly created email
+          #   object.
+          #
+          # @yieldparam [Email] email
+          #   The newly created email object.
+          #
+          # @api public
+          #
+          def initialize(from:       nil,
+                         to:         nil,
+                         subject:    nil,
+                         date:       Time.now,
+                         message_id: nil,
+                         headers:    nil,
+                         body:       nil)
+            @from       = from
+            @to         = to
+            @subject    = subject
+            @date       = date
+            @message_id = message_id
+
+            @headers = {}
+            @headers.merge!(headers) if headers
+
+            @body = []
+
+            if body
+              case body
+              when Array
+                @body += body
+              else
+                @body << body
+              end
+            end
+
+            yield self if block_given?
+          end
+
+          #
+          # Formats the email into a SMTP message.
+          #
+          # @return [String]
+          #   Properly formatted SMTP message.
+          #
+          # @see https://rubydoc.info/stdlib/net/Net/SMTP
+          #
+          # @api public
+          #
+          def to_s
+            address = lambda { |info|
+              case info
+              when Array
+                "#{info[0]} <#{info[1]}>"
+              else
+                info
+              end
+            }
+
+            message = []
+
+            if @from
+              message << "From: #{@from}"
+            end
+
+            if @to
+              message << case @to
+                         when Array
+                           "To: #{@to.join(', ')}"
+                         else
+                           "To: #{@to}"
+                         end
+            end
+
+            if @subject
+              message << "Subject: #{@subject}"
+            end
+
+            if @date
+              message << "Date: #{@date}"
+            end
+
+            if @message_id
+              message << "Message-Id: <#{@message_id}>"
+            end
+
+            @headers.each do |name,value|
+              message << "#{name}: #{value}"
+            end
+
+            message << ''
+            message += @body
+
+            return message.join(CRLF)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/network/smtp/mixin.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/network/smtp/email'
+require 'ronin/support/network/dns/idn'
+require 'ronin/support/network/ssl/mixin'
+
+begin
+  require 'net/smtp'
+rescue LoadError => error
+  warn "ronin/network/smtp requires the net-smtp gem listed in the Gemfile."
+  raise(error)
+end
+
+module Ronin
+  module Support
+    module Network
+      module SMTP
+        #
+        # Provides helper methods for communicating with SMTP services.
+        #
+        module Mixin
+          include SSL::Mixin
+
+          # Default SMTP port
+          DEFAULT_PORT = 25
+
+          #
+          # Creates a properly formatted email.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for
+          #   {Network::SMTP::Email#initialize}.
+          #
+          # @yield [email]
+          #   If a block is given, it will be passed the newly created
+          #   {Network::SMTP::Email} object.
+          #
+          # @yieldparam [Email] email
+          #   The new Email object.
+          #
+          # @return [String]
+          #   Formatted SMTP email.
+          #
+          # @see Email#initialize
+          #
+          # @api public
+          #
+          def self.message(**kwargs,&block)
+            Email.new(**kwargs,&block).to_s
+          end
+
+          #
+          # Creates a new email message.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for
+          #   {Network::SMTP::Email#initialize}.
+          #
+          # @yield [email]
+          #   The given block will be passed the new email.
+          #
+          # @yieldparam [Email] email
+          #   The new email.
+          #
+          # @return [Email]
+          #   the new email message object.
+          #
+          # @see Email#initialize
+          #
+          # @api public
+          #
+          def smtp_message(**kwargs,&block)
+            Email.new(**kwargs,&block)
+          end
+
+          #
+          # Creates a connection to the SMTP server.
+          #
+          # @param [String] host
+          #   The host to connect to.
+          #
+          # @param [String] user
+          #   The user-name to authenticate with.
+          #
+          # @param [String] password
+          #   The password to authenticate with.
+          #
+          # @param [Integer] port
+          #   The port to connect to.
+          #
+          # @param [Boolean, Hash] ssl
+          #   Additional SSL options.
+          #
+          # @option ssl [Boolean] :verify
+          #   Specifies that the SSL certificate should be verified.
+          #
+          # @option ssl [String] :certs
+          #   The path to the file containing CA certs of the server.
+          #
+          # @param [String] helo
+          #   The HELO domain.
+          #
+          # @param [:login, :plain, :cram_md5] auth
+          #   The type of authentication to use. Can be either `:login`,
+          #   `:plain`, or `:cram_md5`.
+          #
+          # @yield [smtp]
+          #   If a block is given, it will be passed an SMTP session object.
+          #   Once the block returns the SMTP session will be closed.
+          #
+          # @yieldparam [Net::SMTP] smtp
+          #   The SMTP session.
+          #
+          # @return [Net::SMTP, nil]
+          #   The SMTP session. If a block is given, then `nil` will be
+          #   returned.
+          #
+          # @example
+          #   smtp_connect('www.example.com', user: 'joe')
+          #
+          # @example
+          #   smtp_connect('www.example.com', user: 'joe') do |smtp|
+          #     # ...
+          #   end
+          #
+          # @api public
+          #
+          def smtp_connect(host, user: ,
+                                 password: , port: DEFAULT_PORT,
+                                 ssl:  nil,
+                                 helo: 'localhost',
+                                 auth: :login)
+            host = DNS::IDN.to_ascii(host)
+            user = user.to_s
+            password = password.to_s
+
+            case ssl
+            when Hash
+              ssl     = true
+              context = ssl_context(ssl)
+            when TrueClass
+              ssl     = true
+              context = ssl_context
+            end
+
+            smtp = Net::SMTP.new(host,port)
+            smtp.enable_starttls(context) if ssl
+            smtp.start(helo,user,password,auth)
+
+            if block_given?
+              yield smtp
+              smtp.finish
+            else
+              return smtp
+            end
+          end
+
+          #
+          # Connects to an SMTP server and sends a message.
+          #
+          # @param [String] host
+          #   The host to connect to.
+          #
+          # @param [Integer] port
+          #   The port to connect to.
+          #
+          # @param [String] user
+          #   The user to authenticate as.
+          #
+          # @param [String] password
+          #   The password to authenticate with.
+          #
+          # @param [Boolean, Hash] ssl
+          #   Additional SSL options.
+          #
+          # @option ssl [Boolean] :verify
+          #   Specifies that the SSL certificate should be verified.
+          #
+          # @option ssl [String] :certs
+          #   The path to the file containing CA certs of the server.
+          #
+          # @param [String] helo
+          #   The HELO domain.
+          #
+          # @param [:login, :plain, :cram_md5] auth
+          #   The type of authentication to use. Can be either `:login`,
+          #   `:plain`, or `:cram_md5`.
+          #
+          # @param [String] from
+          #   The address the email is from.
+          #
+          # @param [Array, String] to
+          #   The address that the email should be sent to.
+          #
+          # @param [String] subject
+          #   The subject of the email.
+          #
+          # @param [String] message_id
+          #   Message-ID of the email.
+          #
+          # @param [String, Time] date
+          #   The date the email was sent on.
+          #
+          # @param [Hash<String => String}] headers
+          #   Additional headers.
+          #
+          # @param [String, Array<String>] body
+          #   The body of the email.
+          #
+          # @yield [email]
+          #   The given block will be passed the new email to be sent.
+          #
+          # @yieldparam [SMTP::Email] email
+          #   The new email to be sent.
+          #
+          # @see #smtp_connect
+          #
+          # @example
+          #   smtp_send_message 'www.example.com',
+          #                     to:         'joe@example.com',
+          #                     from:       'eve@example.com',
+          #                     subject:    'Hello',
+          #                     message_id: 'XXXX',
+          #                     body:       'Hello'
+          #
+          # @example Using the block:
+          #   smtp_send_message('www.example.com') do |email|
+          #     email.to = 'joe@example.com'
+          #     email.from 'eve@example.com'
+          #     email.subject = 'Hello'
+          #     email.message_id = 'XXXXXXXXXX'
+          #     email.body << 'Hello!'
+          #   end
+          #
+          # @since 0.2.0
+          #
+          # @api public
+          #
+          def smtp_send_message(host, user: ,
+                                      password: ,
+                                      # smtp options
+                                      port: DEFAULT_PORT,
+                                      ssl:  nil,
+                                      helo: 'localhost',
+                                      auth: :login,
+                                      # email options
+                                      from:       nil,
+                                      to:         nil,
+                                      subject:    nil,
+                                      date:       Time.now,
+                                      message_id: nil,
+                                      headers:    nil,
+                                      body:       nil,
+                                      &block)
+            email = smtp_message(
+              to:         to,
+              subject:    subject,
+              date:       date,
+              message_id: message_id,
+              headers:    headers,
+              body:       body,
+              &block
+            )
+
+            smtp_connect(host,user,password,
+                         port: port, ssl: ssl, helo: helo, auth: auth) do |smtp|
+              smtp.send_message(email.to_s, email.from, email.to)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/network/smtp.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/network/smtp/email'

data/lib/ronin/support/network/ssl/local_cert.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/home'
+require 'ronin/support/network/ip'
+require 'ronin/support/crypto/cert'
+require 'ronin/support/network/ssl/local_key'
+
+require 'fileutils'
+
+module Ronin
+  module Support
+    module Network
+      module SSL
+        #
+        # Represents the certificate used for local SSL server sockets.
+        #
+        # @api private
+        #
+        module LocalCert
+          # The cached `~/.local/share/ronin/ronin-support/ssl.crt`.
+          PATH = File.join(Home::LOCAL_SHARE_DIR,'ronin','ronin-support','ssl.crt')
+
+          #
+          # Generates a new self-signed SSL certificate using the
+          # {LocalKey local key} and saves it to `~/.local/share/ronin/ssl.crt`.
+          #
+          # @return [Crypto::Cert]
+          #   The newly generated certificate.
+          #
+          # @note
+          #   The file will be created with chmod umask of `0644`
+          #   (aka `-rw-r--r--`).
+          #
+          def self.generate
+            cert = Crypto::Cert.generate(
+              key: LocalKey.fetch,
+              subject: {
+                common_name:         'localhost',
+                organization:        'ronin-rb',
+                organizational_unit: 'ronin-support',
+              },
+              extensions: {
+                'subjectAltName' => subject_alt_name
+              }
+            )
+
+            FileUtils.mkdir_p(File.dirname(PATH))
+            FileUtils.touch(PATH)
+            FileUtils.chmod(0644,PATH)
+
+            cert.save(PATH)
+            return cert
+          end
+
+          #
+          # Loads the local certificate from `~/.local/share/ronin/ssl.crt`.
+          #
+          # @return [Crypto::Cert]
+          #   The loaded certificate.
+          #
+          def self.load
+            Crypto::Cert.load_file(PATH)
+          end
+
+          #
+          # Fetches the default SSL certificate used for all SSL server sockets.
+          #
+          # @return [Crypto::Cert]
+          #   The default SSL certificate.
+          #
+          def self.fetch
+            if File.file?(PATH) then load
+            else                     generate
+            end
+          end
+
+          private
+
+          #
+          # The value for the `subjectAltName` extension.
+          #
+          # @return [String]
+          #
+          def self.subject_alt_name
+            string = String.new("DNS: localhost")
+
+            # append the additional local IP addresses
+            IP.local_addresses.each do |address|
+              string << ", IP: #{address}"
+            end
+
+            return string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/network/ssl/local_key.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/home'
+require 'ronin/support/crypto/key/rsa'
+
+require 'fileutils'
+
+module Ronin
+  module Support
+    module Network
+      module SSL
+        #
+        # Represents the RSA signing key used for local SSL server sockets.
+        #
+        # @api private
+        #
+        module LocalKey
+          # The cached `~/.local/share/ronin/ssl.key` file.
+          PATH = File.join(Home::LOCAL_SHARE_DIR,'ronin','ronin-support','ssl.key')
+
+          #
+          # Generates a new RSA key and saves it to
+          # `~/.local/share/ronin/ssl.key`.
+          #
+          # @return [Crypto::Key::RSA]
+          #   The newly generated key.
+          #
+          # @note
+          #   The file will be created with a chmod umask of `0640`
+          #   (aka `-rw-r-----`).
+          #
+          def self.generate
+            key = Crypto::Key::RSA.generate
+
+            FileUtils.mkdir_p(File.dirname(PATH))
+            FileUtils.touch(PATH)
+            FileUtils.chmod(0640,PATH)
+
+            key.save(PATH)
+            return key
+          end
+
+          #
+          # Loads the RSA key from `~/.local/share/ronin/ssl.key`.
+          #
+          # @return [Crypto::Key::RSA]
+          #   The loaded RSA key.
+          #
+          def self.load
+            Crypto::Key::RSA.load_file(PATH)
+          end
+
+          #
+          # The default RSA key used for all SSL server sockets.
+          #
+          # @return [Crypto::Key::RSA]
+          #   The default RSA key.
+          #
+          def self.fetch
+            if File.file?(PATH) then load
+            else                     generate
+            end
+          end
+        end
+      end
+    end
+  end
+end