ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/encoding/http.rb

@@ -0,0 +1,241 @@
+# 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
+    class Encoding < ::Encoding
+      #
+      # Contains methods for encoding/decoding escaping/unescaping HTTP data.
+      #
+      # ## Features
+      #
+      # * Supports uppercase (ex: `%FF`) and lowercase (ex: `%ff`) URI encoding.
+      #
+      # @api public
+      #
+      module HTTP
+        #
+        # Encodes the byte as an escaped HTTP decimal character.
+        #
+        # @param [Integer] byte
+        #   The byte toe HTTP encode.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:lower, :upper, nil] :case
+        #   Controls whether to output lowercase or uppercase hexadecimal.
+        #   Defaults to uppercase hexadecimal.
+        #
+        # @return [String]
+        #   The encoded HTTP byte.
+        #
+        # @raise [ArgumentError]
+        #   The `case:` keyword argument was not `:lower`, `:upper`, or `nil`.
+        #
+        # @raise [RangeError]
+        #   The byte value is negative or greater than 255.
+        #
+        # @example
+        #   Encoding::HTTP.encode_byte(0x41)
+        #   # => "%41"
+        #
+        # @example Lowercase encoding:
+        #   Encoding::HTTP.encode_byte(0xff, case: :lower)
+        #   # => "%ff"
+        #
+        def self.encode_byte(byte,**kwargs)
+          if (byte >= 0) && (byte <= 0xff)
+            case kwargs[:case]
+            when :lower
+              "%%%.2x" % byte
+            when :upper, nil
+              "%%%.2X" % byte
+            else
+              raise(ArgumentError,"case (#{kwargs[:case].inspect}) keyword argument must be either :lower, :upper, or nil")
+            end
+          else
+            raise(RangeError,"#{byte.inspect} out of char range")
+          end
+        end
+
+        #
+        # HTTP escapes the Integer.
+        #
+        # @param [Integer] byte
+        #   The byte toe HTTP escape.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:lower, :upper, nil] :case
+        #   Controls whether to output lowercase or uppercase hexadecimal.
+        #   Defaults to uppercase hexadecimal.
+        #
+        # @return [String]
+        #   The HTTP escaped form of the Integer.
+        #
+        # @raise [ArgumentError]
+        #   The `case:` keyword argument was not `:lower`, `:upper`, or `nil`.
+        #
+        # @raise [RangeError]
+        #   The byte value is negative or greater than 255.
+        #
+        # @example
+        #   Encoding::HTTP.escape_byte(0x41)
+        #   # => "A"
+        #   Encoding::HTTP.escape_byte(62)
+        #   # => "%3E"
+        #
+        # @example Lowercase encoding:
+        #   Encoding::HTTP.escape_byte(0xff, case: :lower)
+        #   # => "%ff"
+        #
+        def self.escape_byte(byte,**kwargs)
+          if (byte >= 0) && (byte <= 0xff)
+            if (byte == 45) || (byte == 46) || ((byte >= 48) && (byte <= 57)) || ((byte >= 65) && (byte <= 90)) || (byte == 95) || ((byte >= 97) && (byte <= 122)) || (byte == 126)
+              byte.chr
+            elsif byte == 0x20
+              '+'
+            else
+              encode_byte(byte,**kwargs)
+            end
+          else
+            raise(RangeError,"#{byte.inspect} out of char range")
+          end
+        end
+
+        #
+        # HTTP escapes the special characters in the given data.
+        #
+        # @param [String] data
+        #   The data to HTTP escape.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:lower, :upper, nil] :case
+        #   Controls whether to output lowercase or uppercase hexadecimal.
+        #   Defaults to uppercase hexadecimal.
+        #
+        # @return [String]
+        #   The HTTP escaped form of the String.
+        #
+        # @raise [ArgumentError]
+        #   The `case:` keyword argument was not `:lower`, `:upper`, or `nil`.
+        #
+        # @example
+        #   Encoding::HTTP.escape("x > y")
+        #   # => "x+%3E+y"
+        #
+        # @example Lowercase encoding:
+        #   Encoding::HTTP.escape("x > y", case: :lower)
+        #   # => "x+%3e+y"
+        #
+        def self.escape(data,**kwargs)
+          escaped = String.new
+
+          data.each_byte do |byte|
+            escaped << escape_byte(byte,**kwargs)
+          end
+
+          return escaped
+        end
+
+        #
+        # HTTP unescapes the String.
+        #
+        # @param [String] data
+        #   The data to unescape.
+        #
+        # @return [String]
+        #   The raw String.
+        #
+        # @example
+        #   Encoding::HTTP.unescape("sweet+%26+sour")
+        #   # => "sweet & sour"
+        #
+        def self.unescape(data)
+          data.gsub(/(?:\+|%[A-Fa-f0-9]{2})/) do |escaped_char|
+            if escaped_char == '+'
+              ' '
+            else
+              escaped_char[1..].to_i(16).chr
+            end
+          end
+        end
+
+        #
+        # HTTP encodes each byte of the String.
+        #
+        # @param [String] data
+        #   The data to HTTP encode.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:lower, :upper, nil] :case
+        #   Controls whether to output lowercase or uppercase hexadecimal.
+        #   Defaults to uppercase hexadecimal.
+        #
+        # @return [String]
+        #   The HTTP hexadecimal encoded form of the String.
+        #
+        # @raise [ArgumentError]
+        #   The `case:` keyword argument was not `:lower`, `:upper`, or `nil`.
+        #
+        # @example
+        #   Encoding::HTTP.encode("hello")
+        #   # => "%68%65%6c%6c%6f"
+        #
+        # @example Lowercase encoding:
+        #   Encoding::HTTP.encode("hello")
+        #   # => "%68%65%6c%6c%6f"
+        #
+        def self.encode(data,**kwargs)
+          encoded = String.new
+
+          data.each_byte do |byte|
+            encoded << encode_byte(byte,**kwargs)
+          end
+
+          return encoded
+        end
+
+        #
+        # HTTP decodes the HTTP encoded String.
+        #
+        # @param [String] data
+        #   The HTTP encoded data to decode.
+        #
+        # @return [String]
+        #   The decoded String.
+        #
+        # @example
+        #   Encoding::HTTP.decode("sweet+%26+sour")
+        #   # => "sweet & sour"
+        #
+        def self.decode(data)
+          unescape(data)
+        end
+      end
+    end
+  end
+end
+
+require 'ronin/support/encoding/http/core_ext'

data/lib/ronin/support/encoding/js/core_ext/integer.rb

@@ -0,0 +1,67 @@
+# 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/encoding/js'
+
+class Integer
+
+  #
+  # Escapes the Integer as a JavaScript character.
+  #
+  # @return [String]
+  #   The escaped JavaScript character.
+  #
+  # @example 
+  #   0x41.js_escape
+  #   # => "A"
+  #   0x22.js_escape
+  #   # => "\\\""
+  #   0x7f.js_escape
+  #   # => "\\x7F"
+  #
+  # @see Ronin::Support::Encoding::JS.escape_byte
+  #
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  def js_escape
+    Ronin::Support::Encoding::JS.escape_byte(self)
+  end
+
+  #
+  # Encodes the Integer as a JavaScript character.
+  #
+  # @return [String]
+  #   The encoded JavaScript character.
+  #
+  # @example
+  #   0x41.js_encode
+  #   # => "\\x41"
+  #
+  # @see Ronin::Support::Encoding::JS.encode_byte
+  #
+  # @since 1.0.0
+  #
+  # @api public
+  #
+  def js_encode
+    Ronin::Support::Encoding::JS.encode_byte(self)
+  end
+
+end

data/lib/ronin/support/encoding/js/core_ext/string.rb

@@ -0,0 +1,125 @@
+# 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 <http://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/encoding/js'
+
+class String
+
+  #
+  # Escapes a String for JavaScript.
+  #
+  # @return [String]
+  #   The JavaScript escaped String.
+  #
+  # @example
+  #   "hello\nworld\n".js_escape
+  #   # => "hello\\nworld\\n"
+  #
+  # @see Ronin::Support::Encoding::JS.escape
+  #
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  def js_escape
+    Ronin::Support::Encoding::JS.escape(self)
+  end
+
+  #
+  # Unescapes a JavaScript escaped String.
+  #
+  # @return [String]
+  #   The unescaped JavaScript String.
+  #
+  # @example
+  #   "\\u0068\\u0065\\u006C\\u006C\\u006F world".js_unescape
+  #   # => "hello world"
+  #
+  # @see Ronin::Support::Encoding::JS.unescape
+  #
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  def js_unescape
+    Ronin::Support::Encoding::JS.unescape(self)
+  end
+
+  #
+  # JavaScript escapes every character of the String.
+  #
+  # @return [String]
+  #   The JavaScript escaped String.
+  #
+  # @example
+  #   "hello".js_encode
+  #   # => "\\u0068\\u0065\\u006C\\u006C\\u006F"
+  #
+  # @see Ronin::Support::Encoding::JS.encode
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def js_encode
+    Ronin::Support::Encoding::JS.encode(self)
+  end
+
+  alias js_decode js_unescape
+
+  #
+  # Converts the String into a JavaScript string.
+  #
+  # @return [String]
+  #
+  # @example
+  #   "hello\nworld\n".js_string
+  #   # => "\"hello\\nworld\\n\""
+  #
+  # @see Ronin::Support::Encoding::JS.quote
+  #
+  # @since 1.0.0
+  #
+  # @api public
+  #
+  def js_string
+    Ronin::Support::Encoding::JS.quote(self)
+  end
+
+  #
+  # Removes the quotes an unescapes a JavaScript string.
+  #
+  # @return [String]
+  #   The un-quoted String if the String begins and ends with quotes, or the
+  #   same String if it is not quoted.
+  #
+  # @example
+  #   "\"hello\\nworld\"".js_unquote
+  #   # => "hello\nworld"
+  #
+  # @see Ronin::Support::Encoding::JS.unquote
+  #
+  # @since 1.0.0
+  #
+  # @api public
+  #
+  def js_unquote
+    Ronin::Support::Encoding::JS.unquote(self)
+  end
+
+end

data/lib/ronin/support/encoding/js/core_ext.rb

@@ -0,0 +1,20 @@
+# 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/encoding/js/core_ext/integer'
+require 'ronin/support/encoding/js/core_ext/string'