putty-key 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2f25fb48a4e37551a2660d1d4fd3147d3e3170ac
+  data.tar.gz: 8e4bd0d38dbf9a5a56e1e10fdf7db11cd2f7a055
+SHA512:
+  metadata.gz: 54e123b54417b3b2dcb280c6fccb054ae7f4a1d2bb4af8924c33f12886cdea5dcf3d998dbe48c435840578ebed83f471742b45fea808334ebd0010047b1f45bd
+  data.tar.gz: cd8f021629d480f19e4c3b7f628b1b602c318e69ce1316b6619dd6f94b42fc3dd969d2a53b8cbc4e6df1cc655a54dc83512cc74499804fa20fc3cbc26eb0e33b

checksums.yaml.gz.sig

@@ -0,0 +1,3 @@
+1�񨯼]�n]�W��E
����:Q��؃�#� ��5��.�|T�ju���ͱ�gh�#x�?�;���l�y:C�{8��B��hg��@�����Yba��
+�����)��������B�ɵ
+
��R��#��,/��)���-CW��<5A�c�E��+qtN���CV��a����(�S�`��JG�����[�.
��/G?���jf��<+^#�d��K�xb�}'>g^r#�2�'׶��;�X&�7˼OG�Z��5�

data.tar.gz.sig

@@ -0,0 +1 @@
+MI�,�+�^������i�+-�X�6�����&9���W�1=�@�W�V�a��q3#R���+?3�ɐ�A�o�y�Zۄ�毡��(��lvq'fզ��C�y�ĉL��*&{�����Ic���O��M���{{ǥ��>z\}�„,��?
R	'��"�y[��`kf

data/.yardopts

@@ -0,0 +1,7 @@
+--markup=markdown
+--no-private
+lib/**/*.rb
+-
+CHANGES.md
+LICENSE
+README.md

data/CHANGES.md

@@ -0,0 +1,4 @@
+Version 1.0.0 - 2-Apr-2016
+--------------------------
+
+* First release.

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem 'rake', '~> 10.5'
+  gem 'git', '~> 1.2', require: false
+end
+
+group :test do
+  gem 'minitest', '~> 5.8'
+  gem 'simplecov', '~> 0.11', require: false
+  gem 'coveralls', '~> 0.8', require: false
+end

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Philip Ross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# PuTTY::Key #
+
+[![Gem Version](https://badge.fury.io/rb/putty-key.svg)](http://badge.fury.io/rb/putty-key) [![Build Status](https://travis-ci.org/philr/putty-key.svg?branch=master)](https://travis-ci.org/philr/putty-key) [![Coverage Status](https://coveralls.io/repos/philr/putty-key/badge.svg?branch=master)](https://coveralls.io/r/philr/putty-key?branch=master)
+
+PuTTY::Key is a pure-Ruby implementation of the PuTTY private key (ppk) format,
+handling reading and writing .ppk files. It includes a refinement to Ruby's
+OpenSSL library to add support for converting DSA, EC and RSA private keys to
+and from PuTTY private key files. This allows OpenSSH ecdsa, ssh-dss and ssh-rsa
+private keys to be converted to and from PuTTY's private key format.
+
+
+## Installation ##
+
+To install the PuTTY::Key gem, run the following command:
+
+```bash
+gem install putty-key
+```
+
+To add PuTTY::Key as a Bundler dependency, add the following line to your
+`Gemfile`:
+
+```ruby
+gem 'putty-key'
+```
+
+## Compatibility ##
+
+PuTTY::Key is compatible with Ruby MRI 2.1.0+ and Rubinius 2.5.4+ (provided the
+OpenSSL standard library is available).
+
+JRuby will be supported (DSA/DSS and RSA keys only) once jruby-openssl pull
+requests [#82](https://github.com/jruby/jruby-openssl/pull/82) and
+[#83](https://github.com/jruby/jruby-openssl/pull/83) have been released.
+
+
+## Usage ##
+
+To use PuTTY::Key, it must first be loaded with:
+
+```ruby
+require 'putty/key'
+```
+
+The included [refinement](http://ruby-doc.org/core-2.3.0/doc/syntax/refinements_rdoc.html)
+to Ruby's OpenSSL library can then either be activated in the lexical scope
+(file, class or module) where it will be used with:
+
+```ruby
+using PuTTY::Key
+```
+
+or installed globally by calling:
+
+```ruby
+PuTTY::Key.global_install
+```
+
+Note that Rubinius (as of version 3.22) does not support refinements, so the
+global installation approach is required.
+
+JRuby (as of version 9.0.5.0) includes support for refinements, but there are
+still outstanding issues. The global installation approach is preferable on
+JRuby.
+
+The following sections give examples of how PuTTY::Key can be used.
+
+
+### Converting a .pem formatted key file to an unencrypted .ppk file ###
+
+```ruby
+require 'openssl'
+require 'putty/key'
+using PuTTY::Key    # or PuTTY::Key.global_install
+
+pem = File.read('key.pem', mode: 'rb')
+pkey = OpenSSL::PKey.read(pem)
+ppk = pkey.to_ppk
+ppk.comment = 'Optional comment'
+ppk.save('key.ppk')
+```
+
+
+### Generating a new RSA key and saving it as an encrypted .ppk file ###
+
+```ruby
+require 'openssl'
+require 'putty/key'
+using PuTTY::Key    # or PuTTY::Key.global_install
+
+rsa = OpenSSL::PKey::RSA.generate(2048)
+ppk = rsa.to_ppk
+ppk.comment = 'RSA 2048'
+ppk.save('rsa.ppk', 'Passphrase for encryption')
+```
+
+
+### Converting an unencrypted .ppk file to .pem format ###
+
+```ruby
+require 'openssl'
+require 'putty/key'
+using PuTTY::Key    # or PuTTY::Key.global_install
+
+ppk = PuTTY::Key::PPK.new('key.ppk')
+pkey = OpenSSL::PKey.from_ppk(ppk)
+pem = pkey.to_pem
+File.write('key.pem', pem, mode: 'wb')
+```
+
+
+### Decrypting a .ppk file and re-saving it without encryption ###
+
+```ruby
+require 'putty/key'
+
+ppk = PuTTY::Key::PPK.new('rsa.ppk', 'Passphrase for encryption')
+ppk.save('rsa-plain.ppk')
+```
+
+
+## API Documentation ##
+
+API documentation for PuTTY::Key is available on
+[RubyDoc.info](http://www.rubydoc.info/gems/putty-key).
+
+
+## License ##
+
+PuTTY::Key is distributed under the terms of the MIT license. A copy of this
+license can be found in the included LICENSE file.
+
+
+## GitHub Project ##
+
+Source code, release information and the issue tracker can be found on the
+[PuTTY::Key GitHub project page](https://github.com/philr/putty-key).

data/Rakefile

@@ -0,0 +1,110 @@
+require 'fileutils'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/testtask'
+
+BASE_DIR = File.expand_path(File.dirname(__FILE__))
+
+task :default => :test
+
+spec = eval(File.read('putty-key.gemspec'))
+
+# Attempt to find the private key and return a spec with added options for
+# signing the gem if found.
+def add_signing_key(spec)
+  private_key_path = File.expand_path(File.join(BASE_DIR, '..', 'key', 'gem-private_key.pem'))
+
+  if File.exist?(private_key_path)
+    spec = spec.clone
+    spec.signing_key = private_key_path
+    spec.cert_chain = [File.join(BASE_DIR, 'gem-public_cert.pem')]
+  else
+    puts 'WARNING: Private key not found. Not signing gem file.'
+  end
+
+  spec
+end
+
+package_task = Gem::PackageTask.new(add_signing_key(spec)) do
+end
+
+# Ensure files are world-readable before packaging.
+Rake::Task[package_task.package_dir_path].enhance do
+  recurse_chmod(package_task.package_dir_path)
+end
+
+def recurse_chmod(dir)
+  File.chmod(0755, dir)
+
+  Dir.entries(dir).each do |entry|
+    if entry != '.' && entry != '..'
+      path = File.join(dir, entry)
+      if File.directory?(path)
+        recurse_chmod(path)
+      else
+        File.chmod(0644, path)
+      end
+    end
+  end
+end
+
+desc 'Create a tag for the current version'
+task :tag do
+  require 'git'
+  g = Git.init(BASE_DIR)
+  g.add_tag("v#{spec.version}", annotate: true, message: "Tagging v#{spec.version}")
+end
+
+def define_test_task(type, test_coverage)
+  type = type.to_s
+
+  env_task = "test:env:#{type}"
+  Rake::Task::define_task(env_task) do
+    ENV['TEST_COVERAGE'] = test_coverage ? '1' : '0'
+    ENV['TEST_TYPE'] = type
+  end
+
+  test_task = "test:#{type}"
+  Rake::TestTask.new(test_task) do |t|
+    t.libs = [File.join(BASE_DIR, 'test')]
+    t.pattern = File.join(BASE_DIR, 'test', '**', '*_test.rb')
+    t.warning = true
+  end
+
+  Rake::Task[test_task].enhance([env_task])
+end
+
+# JRuby 9.0.5.0 doesn't handle refinements correctly.
+if RUBY_ENGINE == 'jruby'
+  # Don't run coverage tests on JRuby due to inaccurate results.
+  TEST_COVERAGE = false
+
+  task 'test:refinement' do
+    puts 'Skipping refinement tests on JRuby'
+  end
+elsif !respond_to?(:using, true)
+  # Don't run coverage tests on platforms that don't support refinements, since
+  # it won't be possible to get complete coverage.
+  TEST_COVERAGE = false
+
+  task 'test:refinement' do
+    puts "Skipping refinement tests because #{RUBY_DESCRIPTION} lacks support for refinements"
+  end
+else
+  TEST_COVERAGE = true
+  define_test_task(:refinement, TEST_COVERAGE)
+end
+
+define_test_task(:global, TEST_COVERAGE)
+
+require 'coveralls/rake/task'
+Coveralls::RakeTask.new
+
+desc 'Remove coverage results'
+task :clean_coverage do
+  FileUtils.rm_f(File.join(BASE_DIR, 'coverage', '.resultset.json'))
+end
+
+desc 'Run tests using the refinement, then with the global install'
+task :test => [:clean_coverage, 'test:refinement', 'test:global'] + (TEST_COVERAGE ? ['coveralls:push'] : []) do
+end

data/lib/putty/key.rb

@@ -0,0 +1,25 @@
+module PuTTY
+  # PuTTY::Key is a pure-Ruby implementation of the PuTTY private key (ppk)
+  # format, handling reading and writing .ppk files. It includes a refinement to
+  # Ruby's OpenSSL library to add support for converting DSA, EC and RSA private
+  # keys to and from PuTTY private key files. This allows OpenSSH ecdsa, ssh-dss
+  # and ssh-rsa private keys to be converted to and from PuTTY's private key
+  # format.
+  module Key
+
+    # Makes the refinements available in PuTTY::Key available globally. After
+    # calling {global_install}, it is no longer necessary to include
+    # `using PuTTY::Key` when using the `to_ppk` and `from_ppk` methods added to
+    # `OpenSSL::PKey`.
+    def self.global_install
+      ::PuTTY::Key::OpenSSL.global_install
+    end
+  end
+end
+
+require 'putty/key/version'
+require 'putty/key/error'
+require 'putty/key/util'
+require 'putty/key/ppk'
+require 'putty/key/openssl'
+

data/lib/putty/key/error.rb

@@ -0,0 +1,26 @@
+module PuTTY
+  module Key
+    # Base class for all the error classes included in PuTTY::Key.
+    class Error < StandardError
+    end
+
+    # Indicates that an error was encountered in a .ppk file that is being
+    # read or converted to another format.
+    class FormatError < Error
+    end
+
+    # Indicates that an operation cannot be performed with the current state
+    # of the receiver.
+    class InvalidStateError < Error
+    end
+
+    # Indicates that the specified elliptic curve is not supported.
+    class UnsupportedCurveError < Error
+    end
+
+    # Indicates that a nil value has been encountered.
+    class NilValueError < Error
+    end
+    private_constant :NilValueError
+  end
+end

data/lib/putty/key/openssl.rb

@@ -0,0 +1,182 @@
+require 'openssl'
+
+module PuTTY
+  module Key
+    module OpenSSL
+      # {OpenSSL::PKey} classes to be refined.
+      PKEY_CLASSES = Hash[%i(DSA EC RSA).map {|c| [c, ::OpenSSL::PKey.const_get(c)] rescue nil }.compact]
+      private_constant :PKEY_CLASSES
+
+      # Mapping from SSH curve names to their equivalent OpenSSL names.
+      OPENSSL_CURVES = {
+        'nistp256' => 'prime256v1',
+        'nistp384' => 'secp384r1',
+        'nistp521' => 'secp521r1'
+      }
+      private_constant :OPENSSL_CURVES
+
+      # Mapping from OpenSSL curve names to their equivalent SSH names.
+      SSH_CURVES = OPENSSL_CURVES.invert
+      private_constant :SSH_CURVES
+
+      # The {ClassMethods} module is used to extend `OpenSSL::PKey` when
+      # using the PuTTY::Key refinement or calling {PuTTY::Key.global_install}.
+      # This adds a `from_ppk` class method to `OpenSSL::PKey`.
+      #
+      module ClassMethods
+        # Creates a new `OpenSSL::PKey` from a PuTTY private key (instance of
+        # {PPK}).
+        #
+        # This method is called using `OpenSSL::PKey.from_ppk(ppk)`.
+        #
+        # PuTTY keys using the algorithms `ssh-dss`, `ssh-rsa`,
+        # `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384` and `ecdsa-sha2-nistp521`
+        # are supported.
+        #
+        # @return [Object] An instance of either `OpenSSL::PKey::DSA`,
+        #   `OpenSSL::PKey::RSA` or `OpenSSL::PKey::EC` depending on the
+        #   algorithm of `ppk`.
+        #
+        # @raise [ArgumentError] If `ppk` is `nil`.
+        # @raise [ArgumentError] If the algorithm of `ppk` is not supported.
+        def from_ppk(ppk)
+          raise ArgumentError, 'ppk must not be nil' unless ppk
+
+          case ppk.algorithm
+          when 'ssh-dss'
+            ::OpenSSL::PKey::DSA.new.tap do |pkey|
+              _, pkey.p, pkey.q, pkey.g, pkey.pub_key = Util.ssh_unpack(ppk.public_blob, :string, :mpint, :mpint, :mpint, :mpint)
+              pkey.priv_key = Util.ssh_unpack(ppk.private_blob, :mpint).first
+            end
+          when 'ssh-rsa'
+            ::OpenSSL::PKey::RSA.new.tap do |pkey|
+              _, pkey.e, pkey.n = Util.ssh_unpack(ppk.public_blob, :string, :mpint, :mpint)
+              pkey.d, pkey.p, pkey.q, pkey.iqmp = Util.ssh_unpack(ppk.private_blob, :mpint, :mpint, :mpint, :mpint)
+              pkey.dmp1 = pkey.d % (pkey.p - 1)
+              pkey.dmq1 = pkey.d % (pkey.q - 1)
+            end
+          when /\Aecdsa-sha2-(nistp(?:256|384|521))\z/
+            curve = OPENSSL_CURVES[$1]
+
+            # jruby-openssl doesn't include an EC class (version 0.9.16)
+            ec_class = (::OpenSSL::PKey::EC rescue raise ArgumentError, "Unsupported algorithm: #{ppk.algorithm}")
+
+            ec_class.new(curve).tap do |pkey|
+              _, _, point = Util.ssh_unpack(ppk.public_blob, :string, :string, :mpint)
+              pkey.public_key = ::OpenSSL::PKey::EC::Point.new(pkey.group, point)
+              pkey.private_key = Util.ssh_unpack(ppk.private_blob, :mpint).first
+            end
+          else
+            raise ArgumentError, "Unsupported algorithm: #{ppk.algorithm}"
+          end
+        end
+      end
+
+      # The {DSA} module is included into `OpenSSL::PKey::DSA` when using the
+      # PuTTY::Key refinement or calling {PuTTY::Key.global_install}. This adds
+      # a `to_ppk` instance method to `OpenSSL::PKey::DSA`.
+      module DSA
+        # Returns a new {PPK} instance that is equivalent to this key.
+        #
+        # `to_ppk` can be called on instances of `OpenSSL::PKey::DSA`.
+        #
+        # @return [PPK] A new instance of {PPK} that is equivalent to this key.
+        #
+        # @raise [InvalidStateError] If the key has not been initialized.
+        def to_ppk
+          PPK.new.tap do |ppk|
+            ppk.algorithm = 'ssh-dss'
+            begin
+              ppk.public_blob = Util.ssh_pack('ssh-dss', p, q, g, pub_key)
+              ppk.private_blob = Util.ssh_pack(priv_key)
+            rescue NilValueError
+              raise InvalidStateError, 'The key has not been fully initialized (the p, q, g, pub_key and priv_key parameters must all be assigned)'
+            end
+          end
+        end
+      end
+
+      # The {EC} module is included into `OpenSSL::PKey::EC` when using the
+      # PuTTY::Key refinement or calling {PuTTY::Key.global_install}. This adds
+      # a `to_ppk` instance method to `OpenSSL::PKey::EC`.
+      module EC
+        # Returns a new {PPK} instance that is equivalent to this key.
+        #
+        # `to_ppk` can be called on instances of `OpenSSL::PKey::EC`.
+        #
+        # @return [PPK] A new instance of {PPK} that is equivalent to this key.
+        #
+        # @raise [InvalidStateError] If the key has not been initialized.
+        # @raise [UnsupportedCurveError] If the key uses a curve that is not
+        #   supported by PuTTY.
+        def to_ppk
+          curve = group && group.curve_name
+          raise InvalidStateError, 'The key has not been fully initialized (a curve name must be assigned)' unless curve
+          ssh_curve = SSH_CURVES[curve]
+          raise UnsupportedCurveError, "The curve '#{curve}' is not supported" unless ssh_curve
+
+          PPK.new.tap do |ppk|
+            ppk.algorithm = "ecdsa-sha2-#{ssh_curve}"
+            begin
+              ppk.public_blob = Util.ssh_pack(ppk.algorithm, ssh_curve, public_key && public_key.to_bn)
+              ppk.private_blob = Util.ssh_pack(private_key)
+            rescue NilValueError
+              raise InvalidStateError, 'The key has not been fully initialized (public_key and private_key must both be assigned)'
+            end
+          end
+        end
+      end
+
+      # The {RSA} module is included into `OpenSSL::PKey::RSA` when using the
+      # PuTTY::Key refinement or calling {PuTTY::Key.global_install}. This adds
+      # a `to_ppk` instance method to `OpenSSL::PKey::RSA`.
+      module RSA
+        # Returns a new {PPK} instance that is equivalent to this key.
+        #
+        # `to_ppk` can be called on instances of `OpenSSL::PKey::DSA`.
+        #
+        # @return [PPK] A new instance of {PPK} that is equivalent to this key.
+        #
+        # @raise [InvalidStateError] If the key has not been initialized.
+        def to_ppk
+          PPK.new.tap do |ppk|
+            ppk.algorithm = 'ssh-rsa'
+            begin
+              ppk.public_blob = Util.ssh_pack('ssh-rsa', e, n)
+              ppk.private_blob = Util.ssh_pack(d, p, q, iqmp)
+            rescue NilValueError
+              raise InvalidStateError, 'The key has not been fully initialized (the e, n, d, p, q and iqmp parameters must all be assigned)'
+            end
+          end
+        end
+      end
+
+      # Makes the refinements to `OpenSSL` available in PuTTY::Key available
+      # globally. After calling {global_install}, it is no longer necessary to
+      # include `using PuTTY::Key` when using the `to_ppk` and `from_ppk`
+      # methods added to `OpenSSL::PKey`.
+      def self.global_install
+        PKEY_CLASSES.each do |name, openssl_class|
+          mod = const_get(name)
+          openssl_class.class_eval do
+            include mod
+          end
+        end
+
+        ::OpenSSL::PKey.module_eval do
+          extend ClassMethods
+        end
+      end
+    end
+
+    OpenSSL.const_get(:PKEY_CLASSES).each do |name, openssl_class|
+      refine openssl_class do
+        include OpenSSL.const_get(name)
+      end if respond_to?(:refine, true)
+    end
+
+    refine ::OpenSSL::PKey.singleton_class do
+      include OpenSSL::ClassMethods
+    end if respond_to?(:refine, true)
+  end
+end