putty-key 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ee468e63692d4e452273f75c0e2349f451992fa906901f8856685c8c8f2bf82
-  data.tar.gz: 4aafcf168d89410aae4e6f513a10e6fb3261c4a88493ca88125a1ea251cc6721
+  metadata.gz: 7206dacd7197ee9c1344a8cbf607c72614ab3031241bb72a32648bbe62cd784a
+  data.tar.gz: d2835eaa489968b975a93c7cb89e8d7b1dde7e52dc597cc48b54c2b3d9c59c5e
 SHA512:
-  metadata.gz: 67187df6dd956d5067b3a97f35fe53fbb35698f788c5a08f6fd6bf42cc20afcb910fab6773f8af24ac6d53d6f9bd0c23737e47d683921147e9453296d3eed32d
-  data.tar.gz: 7ff5c7f235975206b17da9be813221c4d24e9706e036ef4fc32ed097cfa4ce52deeb11cd9acfc68c218b0e6b7f68d07a54155e81738acd3bf05ca26f75921f03
+  metadata.gz: 0bc6d6331bd8e27ebb082a3bee81b71953cc75e7eea0c80cb6aa3577b4f47a22b379683188a800321848aecffd6e5e6ead37fc1691593c717f9a5b189a03f671
+  data.tar.gz: 5e9b7f92503ba1d3ee96089d42fc20f0ab59203c80c6eca9c2e284df67dacf877356ef6a8bbadca8ac569250f9b965b290f5904bfd6885f9f1648e76c0a39dfc

checksums.yaml.gz.sig

@@ -1 +1,2 @@
-8�Ǜ�#��Z�8�S���B��4a5AYP]�ph�-ܚ�������%�*�x���j?� _����"ME�@c�l���&,��&�i�_�ֹ�8R^U',&aa�A�&"@�~��U'8���XG*�G���6�y��V�z#��0�E�1 �Օ6��k(�Z�C2�/e����6es�^����zBj���f�ڤ��\=F��Px��}��="�X���q
AN�ޜ��g��卹��az�O:d�;���w��ћ�1��M�
+����\�5��dk0���i52����¸����ʍj%��aH!j��v���{��{��|8D���#�}���fjYTr����/b�p����7������ě��t�^*ЅDŸ��)� U�*:�́�G���ԥ̔U��"ᖿ���sZ�)�5XsΞ/�#iQ[�K��,��˃��԰�Xt���ڇeE3�����ە
+�v�1+A����`o��XhȒf6�XQ�����R���	Iҙ�J��&�!á*S

data/CHANGES.md

@@ -1,5 +1,28 @@
 # Changes #
 
+## Version 1.1.1 - 23-Oct-2022 ##
+
+* Add support for Ruby 3.2.
+* Add support for OpenSSL 3 (requires either Ruby 3.1+, or version 3.0.0+ of the
+  openssl gem).
+
+
+## Version 1.1.0 - 24-May-2021 ##
+
+* Add support for [format 3 .ppk files](https://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/ppk3.html)
+  introduced in PuTTY version 0.75. `PuTTY::Key::PPK#save` defaults to saving
+  format 2 files. [libargon2](https://github.com/P-H-C/phc-winner-argon2) is
+  required to load and save encrypted format 3 files.
+* Write files using LF line endings (Unix) instead of CRLF (Windows) to match
+  PuTTYgen version 0.75 (versions up to 0.74 used CRLF, but are compatible with
+  CRLF and LF).
+* Support reading files with CR line endings (Classic Mac OS).
+* Support reading from and writing to `IO`-like streams.
+* Allow loading and saving files with empty private or public keys.
+* Fix adding unnecessary padding to the private key on saving when it is an
+  exact multiple of the block size.
+
+
 ## Version 1.0.1 - 26-Dec-2019 ##
 
 * Fix errors converting DSA and RSA PPK keys to OpenSSL in

data/Gemfile

@@ -12,12 +12,17 @@ group :test do
 
   # coveralls is no longer maintained, but supports Ruby < 2.3.
   # coveralls_reborn is maintained, but requires Ruby >= 2.3.
-  gem 'coveralls', '~> 0.8', require: false if RUBY_VERSION < '2.3'
+  gem 'coveralls', git: 'https://github.com/philr/coveralls-ruby.git', require: false if RUBY_VERSION < '2.3'
   gem 'coveralls_reborn', '~> 0.13', require: false if RUBY_VERSION >= '2.3'
 
-  # json is a dependency of simplecov. Version 2.3.0 is declared as compatible
-  # with Ruby >= 1.9, but actually fails with a syntax error.
+  # The source version of ffi 1.15.5 is declared as compatible with Ruby >= 2.3.
+  # The binary version of 1.15.5 is declared as compatible with Ruby >= 2.4, so
+  # doesn't get used. The using the source version results in a segmentation
+  # fault during libffi initialization.
   #
-  # Limit to earlier versions on Ruby 1.9.
-  gem 'json', '< 2.3.0', require: false if RUBY_VERSION < '2.0'
+  # Binaries of 15.5.0 to 15.5.4 are declared as compatible with Ruby >= 2.3,
+  # but don't get used with Bundler 2.3.23 and Ruby 2.3 on Windows.
+  #
+  # Limit to earlier compatible versions.
+  gem 'ffi', '< 1.15.0' if RUBY_VERSION < '2.4' && RUBY_PLATFORM =~ /mingw/
 end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2019 Philip Ross
+Copyright (c) 2016-2022 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

data/README.md

@@ -1,12 +1,13 @@
 # PuTTY::Key #
 
-[![Gem Version](https://badge.fury.io/rb/putty-key.svg)](https://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) [![Build status](https://ci.appveyor.com/api/projects/status/btinuu4g8sdachj3/branch/master?svg=true)](https://ci.appveyor.com/project/philr/tzinfo/branch/master) [![Coverage Status](https://coveralls.io/repos/philr/putty-key/badge.svg?branch=master)](https://coveralls.io/r/philr/putty-key?branch=master)
+[![RubyGems](https://img.shields.io/gem/v/putty-key?logo=rubygems&label=Gem)](https://rubygems.org/gems/putty-key) [![Tests](https://github.com/philr/putty-key/workflows/Tests/badge.svg?branch=master&event=push)](https://github.com/philr/putty-key/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush) [![Coverage Status](https://img.shields.io/coveralls/github/philr/putty-key/master?label=Coverage&logo=Coveralls)](https://coveralls.io/github/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.
+PuTTY::Key is a Ruby implementation of the PuTTY private key (ppk) format
+(versions 2 and 3), 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 ##
@@ -29,6 +30,22 @@ gem 'putty-key'
 PuTTY::Key is compatible with Ruby MRI 2.1.0+ and JRuby 9.1.0.0+.
 
 
+## Formats ##
+
+Format 2 and 3 .ppk files are supported. Format 1 (not supported) was only used
+briefly early on in the development of the .ppk format and was never included in
+a PuTTY release. Format 2 is supported by PuTTY version 0.52 onwards. Format 3
+is supported by PuTTY version 0.75 onwards. By default, `PuTTY::Key::PPK` saves
+files using format 2. Format 3 can be selected with the `format` parameter.
+
+[libargon2](https://github.com/P-H-C/phc-winner-argon2) is required to load and
+save encrypted format 3 files. Binaries are typically available with your OS
+distribution. For Windows, binaries are available from the
+[argon2-windows](https://github.com/philr/argon2-windows/releases) repository.
+Use either Argon2OptDll.dll for CPUs supporting AVX or Argon2RefDll.dll
+otherwise.
+
+
 ## Usage ##
 
 To use PuTTY::Key, it must first be loaded with:
@@ -68,6 +85,9 @@ ppk.comment = 'Optional comment'
 ppk.save('key.ppk')
 ```
 
+Use `ppk.save('key.ppk', format: 3)` to save a format 3 file instead of
+format 2.
+
 
 ### Generating a new RSA key and saving it as an encrypted .ppk file ###
 
@@ -82,6 +102,9 @@ ppk.comment = 'RSA 2048'
 ppk.save('rsa.ppk', 'Passphrase for encryption')
 ```
 
+Use `ppk.save('rsa.ppk', 'Passphrase for encryption', format: 3)` to save a
+format 3 file instead of format 2.
+
 
 ### Converting an unencrypted .ppk file to .pem format ###
 
@@ -106,6 +129,9 @@ ppk = PuTTY::Key::PPK.new('rsa.ppk', 'Passphrase for encryption')
 ppk.save('rsa-plain.ppk')
 ```
 
+Use `ppk.save('rsa-plain.ppk', format: 3)` to save a format 3 file instead of
+format 2.
+
 
 ## API Documentation ##
 

data/Rakefile

@@ -105,3 +105,27 @@ 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
+
+# Coveralls expects an sh compatible shell when running git commands with Kernel#`
+# On Windows, the results end up wrapped in single quotes.
+# Patch Coveralls::Configuration to remove the quotes.
+if RUBY_PLATFORM =~ /mingw/
+  module CoverallsFixConfigurationOnWindows
+    def self.included(base)
+      base.instance_eval do
+        class << self
+          alias_method :git_without_windows_fix, :git
+
+          def git
+            git_without_windows_fix.tap do |hash|
+              hash[:head] = hash[:head].map {|k, v| [k, v =~ /\A'(.*)'\z/ ? $1 : v] }.to_h
+            end
+          end
+        end
+      end
+    end
+  end
+
+  require 'coveralls'
+  Coveralls::Configuration.send(:include, CoverallsFixConfigurationOnWindows)
+end

data/lib/putty/key/argon2_params.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module PuTTY
+  module Key
+    # Argon2 key derivation parameters for use with format 3.
+    class Argon2Params
+      # Returns the variant of Argon2 to use. `:d` for Argon2d, `:i` for Argon2i
+      # or `:id` for Argon2id.
+      #
+      # @return [Symbol] The variant of Argon2 to use (`:d`, `:i` or `:id`).
+      attr_reader :type
+
+      # @return [Integer] The amount of memory to use (memory cost) in
+      #   kibibytes.
+      attr_reader :memory
+
+      # @return [Integer] The number of parallel threads to use (parallelism
+      #   degree / lanes).
+      attr_reader :parallelism
+
+      # @return [Integer] The number of passes or iterations to run (time cost),
+      #   or `nil` to determine the time cost based on {#desired_time}.
+      attr_reader :passes
+
+      # @return [String] The salt to use, or `nil` if a random salt should be
+      #   selected.
+      attr_reader :salt
+
+      # The minimum time that should be taken to derive keys in milliseconds.
+      # Only used if {#passes} is `nil`.
+      #
+      # A number of passes will be chosen that take at least {#desired_time} to
+      # compute a hash.
+      #
+      # @return [Numeric] The minimum time that should be taken to derive keys
+      #   in milliseconds.
+      attr_reader :desired_time
+
+      # Initalizes a new {Argon2Params} instance with the specified parameters.
+      #
+      # @param type [Symbol] The variant of Argon2 to use (`:d`, `:i` or `:id`).
+      # @param memory [Integer] The amount of memory to use (memory cost) in
+      #   kibibytes.
+      # @param parallelism [Integer] The number of parallel threads to use
+      #   (parallelism degree / lanes).
+      # @param passes [Integer] The number of passes or iterations to run (time
+      #   cost), or `nil` to determine the time cost based on {#desired_time}.
+      # @param salt [String] The salt to use, or `nil` if a random salt should
+      #   be selected.
+      # @param desired_time [Numeric] The minimum time that should be taken to
+      #   derive keys in milliseconds.
+      #
+      # @raise [ArgumentError] If `type` is not either `:d`, `:i` or `:id`.
+      # @raise [ArgumentError] If `memory` is not an `Integer`, is negative or
+      #   greater than 2³².
+      # @raise [ArgumentError] If `parallelism` is not an `Integer`, is negative
+      #   or greater than 2³².
+      # @raise [ArgumentError] If `passes` is specified, but is not an
+      #   `Integer`, is negative or greater than 2³².
+      # @raise [ArgumentError] If `salt` is specified, but is not a `String`.
+      # @raise [ArgumentError] If `desired_time` is not `Numeric` or is
+      #   negative.
+      def initialize(type: :id, memory: 8192, parallelism: 1, passes: nil, salt: nil, desired_time: 100)
+        raise ArgumentError, 'type must be :d, :i or :id' unless type == :id || type == :i || type == :d
+        raise ArgumentError, 'memory must be a non-negative Integer' unless memory.kind_of?(Integer) && memory >= 0 && memory <= 2**32
+        raise ArgumentError, 'parallelism must be a non-negative Integer' unless parallelism.kind_of?(Integer) && parallelism >= 0 && parallelism <= 2**32
+        raise ArgumentError, 'passes must be nil or a non-negative Integer' if passes && !(passes.kind_of?(Integer) && passes >= 0 && passes <= 2**32)
+        raise ArgumentError, 'salt must be nil or a String' if salt && !salt.kind_of?(String)
+        raise ArgumentError, 'desired_time must be a non-negative Numeric' unless desired_time.kind_of?(Numeric) && desired_time >= 0 && desired_time <= 2**32
+
+        @type = type
+        @memory = memory
+        @parallelism = parallelism
+        @passes = passes
+        @salt = salt
+        @desired_time = desired_time
+      end
+
+      # Returns an instance of {Argon2Params} with the actual number of passes
+      # and salt used.
+      #
+      # @param actual_passes [Integer] The number of passes or iterations used.
+      # @param actual_salt [String] The actual salt used.
+      #
+      # @return [Argon2Params] An instance of {Argon2Params} with the given
+      #   passes and salt.
+      #
+      # @raise [ArgumentError] If `actual_passes` is not a positive `Integer`.
+      # @raise [ArgumentError] If `actual_salt` is not a `String`.
+      def complete(passes, salt)
+        raise ArgumentError, 'passes must not be nil' unless passes
+        raise ArgumentError, 'salt must not be nil' unless salt
+        if @passes == passes && @salt == salt
+          self
+        else
+          Argon2Params.new(type: @type, memory: @memory, parallelism: @parallelism, passes: passes, salt: salt, desired_time: @desired_time)
+        end
+      end
+    end
+  end
+end

data/lib/putty/key/error.rb

@@ -18,6 +18,23 @@ module PuTTY
     class UnsupportedCurveError < Error
     end
 
+    # Indicates that libargon2 encountered an error hashing the passphrase to
+    # derive the keys for a format 3 .ppk file.
+    class Argon2Error < Error
+      # The error code returned by the `argon2_hash` function.
+      attr_reader :error_code
+
+      # Initializes a new {Argon2Error}.
+      #
+      # @param error_code [Integer] The error code returned by the `argon2_hash`
+      #   function.
+      # @param message [String] A description of the error.
+      def initialize(error_code, message)
+        super(message)
+        @error_code = error_code
+      end
+    end
+
     # Indicates that a nil value has been encountered.
     class NilValueError < Error
     end

data/lib/putty/key/libargon2.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module PuTTY
+  module Key
+    # A wrapper for the required functions from libargon2.
+    module Libargon2
+      extend ::FFI::Library
+
+      ffi_lib ['argon2', 'libargon2.so.1', 'libargon2.dll', 'Argon2OptDll.dll', 'Argon2RefDll.dll']
+
+      # Returned by `argon2_hash` if successful.
+      ARGON2_OK = 0
+
+      # The type of hash to perform.
+      enum :argon2_type, [:d, 0, :i, 1, :id, 2]
+
+      # The version of the algorithm to use.
+      enum FFI::Type::UINT32, :argon2_version, [:version_10, 0x10, :version_13, 0x13]
+
+      # Hashes a password with Argon2, producing a raw hash at hash.
+      #
+      #   t_cost Number of iterations.
+      #   m_cost Sets memory usage to m_cost kibibytes.
+      #   parallelism Number of threads and compute lanes.
+      #   pwd Pointer to password.
+      #   pwdlen Password size in bytes.
+      #   salt Pointer to salt.
+      #   saltlen Salt size in bytes.
+      #   hash Buffer where to write the raw hash - updated by the function.
+      #   hashlen Desired length of the hash in bytes.
+      #
+      # Different parallelism levels will give different results.
+      #
+      # Returns ARGON2_OK if successful.
+      #
+      # ARGON2_PUBLIC int argon2_hash(const uint32_t t_cost, const uint32_t m_cost,
+      #                               const uint32_t parallelism, const void *pwd,
+      #                               const size_t pwdlen, const void *salt,
+      #                               const size_t saltlen, void *hash,
+      #                               const size_t hashlen, char *encoded,
+      #                               const size_t encodedlen, argon2_type type,
+      #                               const uint32_t version);
+      attach_function 'argon2_hash', [:uint32, :uint32, :uint32, :pointer, :size_t, :pointer, :size_t, :pointer, :size_t, :pointer, :size_t, :argon2_type, :argon2_version], :int
+
+      # Returns an error message corresponding to the given error code.
+      #
+      # ARGON2_PUBLIC const char *argon2_error_message(int error_code);
+      attach_function :argon2_error_message, [:int], :string
+    end
+    private_constant :Libargon2
+  end
+end