ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/crypto/key/dh.rb

@@ -0,0 +1,122 @@
+# 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/crypto/key/methods'
+require 'ronin/support/crypto/openssl'
+
+module Ronin
+  module Support
+    module Crypto
+      module Key
+        #
+        # Represents an Diffie-Hellman (DH) key.
+        #
+        # @see https://rubydoc.info/stdlib/openssl/OpenSSL/PKey/DH.html
+        #
+        # @since 1.0.0
+        #
+        # @api public
+        #
+        class DH < OpenSSL::PKey::DH
+
+          include Methods
+
+          #
+          # Generates a new DH key.
+          #
+          # @param [Integer] key_size
+          #   The size of the key in bits.
+          #
+          # @param [Integer, nil] generator
+          #   A small number > 1, typically 2 or 5.
+          #
+          # @return [DH]
+          #   The newly generated key.
+          #
+          # @note
+          #   jruby's openssl does not define `OpenSSL::PKey::DH.generate`.
+          #   See https://github.com/jruby/jruby-openssl/issues/254
+          #
+          def self.generate(key_size=1024, generator: nil)
+            new_key = allocate
+            new_key.send(:initialize_copy,super(key_size,*generator))
+            new_key
+          end
+
+          #
+          # The `p` variable for the DH key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def p
+            super()
+          end
+
+          #
+          # The `q` variable for the DH key.
+          #
+          # @return [OpenSSL::BN, nil]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          # @note
+          #   jruby's openssl does not implement `OpenSSL::PKey::DH#q`.
+          #   See https://github.com/jruby/jruby-openssl/issues/253
+          #
+          def q
+            super() unless RUBY_ENGINE == 'jruby'
+          end
+
+          #
+          # The `g` variable for the DH key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def g
+            super()
+          end
+
+          #
+          # The size of the DH key in bits.
+          #
+          # @return [Integer]
+          #   The key size in bits.
+          #
+          def size
+            p.num_bits
+          end
+
+          #
+          # Saves the DH key to the given file.
+          #
+          # @param [String] path
+          #   The path to the output file.
+          #
+          def save(path)
+            super(path)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/crypto/key/dsa.rb

@@ -0,0 +1,103 @@
+# 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/crypto/key/methods'
+require 'ronin/support/crypto/openssl'
+
+module Ronin
+  module Support
+    module Crypto
+      module Key
+        #
+        # Represents an DSA key.
+        #
+        # @see https://rubydoc.info/stdlib/openssl/OpenSSL/PKey/DSA.html
+        #
+        # @since 1.0.0
+        #
+        # @api public
+        #
+        class DSA < OpenSSL::PKey::DSA
+
+          include Methods
+
+          #
+          # Generates a new random DSA key.
+          #
+          # @param [Integer] key_size
+          #   The size of the key in bits.
+          #
+          # @return [DSA]
+          #   The newly generated key.
+          #
+          def self.generate(key_size=1024)
+            # HACK: openssl-3.0.0 will return an OpenSSL::PKey::SAA instance,
+            # even though we subclassed OpenSSL::PKey::SAA.
+            new_key = allocate
+            new_key.send(:initialize_copy,super(key_size))
+            new_key
+          end
+
+          #
+          # The `p` variable for the DSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def p
+            super()
+          end
+
+          #
+          # The `q` variable for the DSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def q
+            super()
+          end
+
+          #
+          # The `g` variable for the DSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def g
+            super()
+          end
+
+          #
+          # The size of the DSA key in bits.
+          #
+          # @return [Integer]
+          #   The key size in bits.
+          #
+          def size
+            p.num_bits
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/crypto/key/ec.rb

@@ -0,0 +1,99 @@
+# 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/crypto/key/methods'
+require 'ronin/support/crypto/openssl'
+
+module Ronin
+  module Support
+    module Crypto
+      module Key
+        #
+        # Represents an EC key.
+        #
+        # ## Examples
+        #
+        # ### List supported curves
+        #
+        #     Crypto::Key::EC.supported_curves
+        #     # => ["secp224r1", "secp256k1", "secp384r1", "secp521r1", "prime256v1"]
+        #
+        # ### Generate a random key
+        #
+        #     ec = Crypto::Key::EC.random("secp224r1")
+        #
+        # @see https://rubydoc.info/stdlib/openssl/OpenSSL/PKey/EC.html
+        #
+        # @since 1.0.0
+        #
+        # @api public
+        #
+        class EC < OpenSSL::PKey::EC
+
+          include Methods
+
+          #
+          # The supported elliptical curves.
+          #
+          # @return [Array<String>]
+          #   The supported curve names.
+          #
+          def self.supported_curves
+            builtin_curves.map { |(name,desc)| name }
+          end
+
+          #
+          # Generates a new random EC key.
+          #
+          # @param [String] curve
+          #   The curve to use. See {supported_curves}.
+          #
+          # @return [EC]
+          #   The newly generated key.
+          #
+          def self.generate(curve='prime256v1')
+            super(curve)
+          end
+
+          #
+          # Initializes the EC key.
+          #
+          # @param [Array] args
+          #   Additional arguments.
+          #
+          # @note
+          #   Will print a warning message when running on JRuby about
+          #   jruby-openssl's EC key bugs:
+          #   * https://github.com/jruby/jruby-openssl/issues/256
+          #   *https://github.com/jruby/jruby-openssl/issues/257
+          #
+          def initialize(*args)
+            if RUBY_ENGINE == 'jruby'
+              warn "WARNING: jruby-openssl has multiple bugs wrt parsing EC keys"
+              warn " * https://github.com/jruby/jruby-openssl/issues/256"
+              warn " * https://github.com/jruby/jruby-openssl/issues/257"
+            end
+
+            super(*args)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/crypto/key/methods.rb

@@ -0,0 +1,163 @@
+# 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/crypto/openssl'
+
+module Ronin
+  module Support
+    module Crypto
+      module Key
+        #
+        # Common methods for {Key} classes.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        module Methods
+          #
+          # Extends {ClassMethods}.
+          #
+          # @param [Class] key_class
+          #   The {Key} class that is including {Methods}.
+          #
+          def self.included(key_class)
+            key_class.extend ClassMethods
+          end
+
+          module ClassMethods
+            #
+            # Generates a new random key.
+            #
+            # @param [Array] arguments
+            #   Additional arguments for `generate`.
+            #
+            # @return [Class<Methods>]
+            #   The newly generated key.
+            #
+            # @note Alias for `generate`.
+            #
+            def random(*arguments,&block)
+              generate(*arguments,&block)
+            end
+
+            #
+            # Parses an PEM encoded key.
+            #
+            # @param [String] key
+            #   The PEM or DER encoded key string.
+            #
+            # @param [String, nil] password
+            #   Optional password to decrypt the key.
+            #
+            # @return [OpenSSL::PKey]
+            #   The parsed key.
+            #
+            # @api public
+            #
+            def parse(key, password: nil)
+              new(key,*password)
+            end
+
+            #
+            # Alias for {#parse}.
+            #
+            # @param [String] key
+            #   The PEM or DER encoded key string.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments for {#parse}.
+            #
+            # @option kwargs [String, nil] :password
+            #   Optional password to decrypt the key.
+            #
+            # @return [OpenSSL::PKey]
+            #   The parsed key.
+            #
+            # @see parse
+            #
+            # @api public
+            #
+            def load(key,**kwargs)
+              parse(key,**kwargs)
+            end
+
+            #
+            # Loads a key from a file.
+            #
+            # @param [String] path
+            #   The path to the PEM or DER encoded key file.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments for {parse}.
+            #
+            # @option kwargs [String, nil] :password
+            #   Optional password to decrypt the key.
+            #
+            # @return [OpenSSL::PKey]
+            #   The parsed key.
+            #
+            # @api public
+            #
+            def load_file(path,**kwargs)
+              parse(File.read(path),**kwargs)
+            end
+          end
+
+          #
+          # Saves the key to the given path.
+          #
+          # @param [String] path
+          #   The path to write the exported key to.
+          #
+          # @param [:pem, :der] encoding
+          #   The desired encoding of the exported key.
+          #   * `:pem` - PEM encoding.
+          #   * `:der` - DER encoding.
+          #
+          # @param [String, nil] cipher
+          #   Optional cipher to use to encrypt the key file.
+          #
+          # @param [String, nil] password
+          #   Optional password to use to encrypt the key file.
+          #
+          # @raise [ArgumentError]
+          #   The `endcoding:` value must be either `:pem` or `:der`.
+          #
+          def save(path, encoding: :pem, cipher: 'aes-256-cbc', password: nil)
+            encoding_method = case encoding
+                              when :pem then method(:to_pem)
+                              when :der then method(:to_der)
+                              else
+                                raise(ArgumentError,"encoding: keyword argument (#{encoding.inspect}) must be either :pem or :der")
+                              end
+
+            exported = if password
+                         cipher = OpenSSL::Cipher.new(cipher)
+                         encoding_method.call(cipher,password)
+                       else
+                         encoding_method.call()
+                       end
+
+            File.write(path,exported)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/crypto/key/rsa.rb

@@ -0,0 +1,169 @@
+# 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/crypto/key/methods'
+require 'ronin/support/crypto/openssl'
+
+module Ronin
+  module Support
+    module Crypto
+      module Key
+        #
+        # Represents an RSA key.
+        #
+        # @see https://rubydoc.info/stdlib/openssl/OpenSSL/PKey/RSA.html
+        #
+        # @since 1.0.0
+        #
+        # @api public
+        #
+        class RSA < OpenSSL::PKey::RSA
+
+          include Methods
+
+          #
+          # Generates a new random RSA key.
+          #
+          # @param [Integer] key_size
+          #   The size of the key in bits.
+          #
+          # @param [Array] arguments
+          #   Additional arguments for [OpenSSL::PKey::RSA.generate](https://rubydoc.info/gems/openssl/OpenSSL/PKey/RSA#generate-class_method).
+          #
+          # @return [RSA]
+          #   The newly generated key.
+          #
+          def self.generate(key_size=4096,*arguments,&block)
+            # HACK: openssl-3.0.0 will return an OpenSSL::PKey::RSA instance,
+            # even though we subclassed OpenSSL::PKey::RSA.
+            new_key = allocate
+            new_key.send(:initialize_copy,super(key_size,*arguments,&block))
+            new_key
+          end
+
+          #
+          # The `n` variable for the RSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def n
+            super()
+          end
+
+          #
+          # The `e` variable for the RSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def e
+            super()
+          end
+
+          #
+          # The `d` variable for the RSA key.
+          #
+          # @return [OpenSSL::BN]
+          #
+          # @see https://rubydoc.info/stdlib/openssl/OpenSSL/BN
+          #
+          def d
+            super()
+          end
+
+          #
+          # The size of the RSA key in bits.
+          #
+          # @return [Integer]
+          #   The key size in bits.
+          #
+          def size
+            n.num_bits
+          end
+
+          # Mapping of padding names to pdding constants.
+          #
+          # @api private
+          PADDINGS = {
+            pkcs1_oaep: PKCS1_OAEP_PADDING,
+            pkcs1:      PKCS1_PADDING,
+            sslv23:     SSLV23_PADDING,
+
+            nil      => NO_PADDING,
+            false    => NO_PADDING
+          }
+
+          #
+          # Encrypts data using the public key.
+          #
+          # @param [String] data
+          #   The data to encrypt.
+          #
+          # @param [:pkcs1_oaep, :pkcs1, :sslv23, nil, false] padding
+          #   Optional padding mode. `nil` and `false` will disable padding.
+          #
+          # @return [String]
+          #   The encrypted data.
+          #
+          # @example
+          #   rsa = Crypto::Key::RSA.load_file('key.pem')
+          #   rsa.public_encrypt("top secret", padding: :pkcs1_oaep)
+          #   # => "i;k\x89\xE9\x92\xA5\xAB\xBAc\xC6;\r\xB7\x18W\x11\x02\xCBf.\xC2\x87\xDF\xDD[|\xF0\x97\x15\xC6\xCF\xCD\x93\x1C\x11S&L\x89\xE6\xCA\xC9\xAD\xAD\x1F\xE6\x8D\x86\xF3$\x8BfS(3\x9F\x7F\xEFZ \xB7\xDC{f\xF1\xB7-\x18\x94\xB8}\x93%,{X\x85\xBD(\xBD\xAD\x00,O\xAC\xECJ}\x99\xC7\xE2\xB6\x11\x9D\xDF\x12\xA5\x8F|\xF8\xC3Q\xDA\x95\x12\xEFH\xFFt\xCD\x854jJ\xE9\xE7\xC4\xDD|\xD4}w\xDAJ8\xAE\x17"
+          #
+          def public_encrypt(data, padding: :pkcs1)
+            padding_const = PADDINGS.fetch(padding) do
+              raise(ArgumentError,"padding must be #{PADDINGS.keys.map(&:inspect).join(', ')}: #{padding.inspect}")
+            end
+
+            super(data,padding_const)
+          end
+
+          #
+          # Decrypts data using the private key.
+          #
+          # @param [String] data
+          #   The data to decrypt.
+          #
+          # @param [:pkcs1_oaep, :pkcs1, :sslv23, nil, false] padding
+          #   Optional padding mode. `nil` and `false` will disable padding.
+          #
+          # @return [String]
+          #   The decrypted data.
+          #
+          # @example
+          #   encrypted = "i;k\x89\xE9\x92\xA5\xAB\xBAc\xC6;\r\xB7\x18W\x11\x02\xCBf.\xC2\x87\xDF\xDD[|\xF0\x97\x15\xC6\xCF\xCD\x93\x1C\x11S&L\x89\xE6\xCA\xC9\xAD\xAD\x1F\xE6\x8D\x86\xF3$\x8BfS(3\x9F\x7F\xEFZ \xB7\xDC{f\xF1\xB7-\x18\x94\xB8}\x93%,{X\x85\xBD(\xBD\xAD\x00,O\xAC\xECJ}\x99\xC7\xE2\xB6\x11\x9D\xDF\x12\xA5\x8F|\xF8\xC3Q\xDA\x95\x12\xEFH\xFFt\xCD\x854jJ\xE9\xE7\xC4\xDD|\xD4}w\xDAJ8\xAE\x17"
+          #   rsa = Crypto::Key::RSA.load_file('key.pem')
+          #   rsa.private_decrypt(encrypted, padding: pkcs1_oaep)
+          #   # => "top secret"
+          #
+          def private_decrypt(data, padding: :pkcs1)
+            padding_const = PADDINGS.fetch(padding) do
+              raise(ArgumentError,"padding must be #{PADDINGS.keys.map(&:inspect).join(', ')}: #{padding.inspect}")
+            end
+
+            super(data,padding_const)
+          end
+
+        end
+      end
+    end
+  end
+end