putty-key 1.0.1 → 1.1.1

data/lib/putty/key/ppk.rb

@@ -7,9 +7,11 @@ module PuTTY
     # Represents a PuTTY private key (.ppk) file.
     #
     # The {PPK} {#initialize constructor} can be used to either create an
-    # uninitialized key or to load a .ppk file.
+    # uninitialized key or to read a .ppk file (from file or an `IO`-like
+    # instance).
     #
-    # The {#save} method can be used to save a {PPK} instance to a .ppk file.
+    # The {#save} method can be used to write a {PPK} instance to a .ppk file or
+    # `IO`-like instance.
     #
     # The {#algorithm}, {#comment}, {#public_blob} and {#private_blob}
     # attributes provide access to the high level fields of the PuTTY private
@@ -17,23 +19,45 @@ module PuTTY
     # based on the algorithm.
     #
     # Encrypted .ppk files can be read and written by specifying a passphrase
-    # when loading or saving. As supported by PuTTY, files are always encrypted
-    # using AES in CBC mode with a 256-bit key derived from the passphrase using
-    # SHA-1.
+    # when loading or saving. Files are encrypted using AES in CBC mode with a
+    # 256-bit key derived from the passphrase.
     #
-    # The {PPK} class supports files corresponding to PuTTY's format 2. Format 1
-    # was only used briefly early on in the development of the .ppk format.
+    # The {PPK} class supports files corresponding to PuTTY's formats 2 and 3.
+    # Format 1 (not supported) was only used briefly early on in the development
+    # of the .ppk format and was never released. Format 2 is supported by PuTTY
+    # version 0.52 onwards. Format 3 is supported by PuTTY version 0.75 onwards.
+    # {PPK#save} defaults to format 2. Use the `format` parameter to select
+    # format 3.
+    #
+    # 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 at
+    # https://github.com/philr/argon2-windows/releases - use either
+    # Argon2OptDll.dll for CPUs supporting AVX or Argon2RefDll.dll otherwise.
     class PPK
-      # String used in the computation of the private MAC.
-      MAC_KEY = 'putty-private-key-file-mac-key'
-      private_constant :MAC_KEY
+      # String used in the computation of the format 3 MAC.
+      FORMAT_2_MAC_KEY = 'putty-private-key-file-mac-key'
+      private_constant :FORMAT_2_MAC_KEY
+
+      # Length of the key used for the format 3 MAC.
+      FORMAT_3_MAC_KEY_LENGTH = 32
+      private_constant :FORMAT_3_MAC_KEY_LENGTH
 
       # The default (and only supported) encryption algorithm.
       DEFAULT_ENCRYPTION_TYPE = 'aes256-cbc'.freeze
 
-      # The default (and only supported) PuTTY private key file format.
+      # The default PuTTY private key file format.
       DEFAULT_FORMAT = 2
 
+      # The mimimum supported PuTTY private key file format.
+      MINIMUM_FORMAT = 2
+
+      # The maximum supported PuTTY private key file format.
+      MAXIMUM_FORMAT = 3
+
+      # Default Argon2 key derivation parameters for use with format 3.
+      DEFAULT_ARGON2_PARAMS = Argon2Params.new.freeze
+
       # The key's algorithm, for example, 'ssh-rsa' or 'ssh-dss'.
       #
       # @return [String] The key's algorithm, for example, 'ssh-rsa' or
@@ -59,70 +83,116 @@ module PuTTY
       # @return [String] The private component of the key
       attr_accessor :private_blob
 
-      # Constructs a new {PPK} instance either uninitialized, or by loading a
-      # .ppk file.
+      # Constructs a new {PPK} instance either uninitialized, or initialized
+      # by reading from a .ppk file or an `IO`-like instance.
+      #
+      # To read from a file set `path_or_io` to the file path, either as a
+      # `String` or a `Pathname`. To read from an `IO`-like instance set
+      # `path_or_io` to the instance. The instance must respond to `#read`.
+      # `#binmode` will be called before reading if supported by the instance.
       #
-      # @param path [Object] Set to the path of a .ppk file to load the file.
-      #   Leave as `nil` to leave the new {PPK} instance uninitialized.
+      # @param path_or_io [Object] Set to the path of a .ppk file to load the
+      #   file as a `String` or `Pathname`, or an `IO`-like instance to read the
+      #   .ppk file from that instance. Set to `nil` to leave the new {PPK}
+      #   instance uninitialized.
       # @param passphrase [String] The passphrase to use when loading an
       #   encrypted .ppk file.
       #
       # @raise [Errno::ENOENT] If the file specified by `path` does not exist.
       # @raise [ArgumentError] If the .ppk file was encrypted, but either no
       #   passphrase or an incorrect passphrase was supplied.
-      # @raise [FormatError] If the .ppk file is malformed.
-      def initialize(path = nil, passphrase = nil)
+      # @raise [FormatError] If the .ppk file is malformed or not supported.
+      # @raise [LoadError] If opening an encrypted format 3 .ppk file and
+      #   libargon2 could not be loaded.
+      # @raise [Argon2Error] If opening an encrypted format 3 .ppk file and
+      #   libargon2 reported an error hashing the passphrase.
+      def initialize(path_or_io = nil, passphrase = nil)
         passphrase = nil if passphrase && passphrase.to_s.empty?
 
-        if path
-          encryption_type, encrypted_private_blob, private_mac = Reader.open(path) do |reader|
-            @algorithm = reader.field('PuTTY-User-Key-File-2')
+        if path_or_io
+          Reader.open(path_or_io) do |reader|
+            format, @algorithm = reader.field_matching(/PuTTY-User-Key-File-(\d+)/)
+            format = format.to_i
+            raise FormatError, "The ppk file is using a format that is too new (#{format})" if format > MAXIMUM_FORMAT
+            raise FormatError, "The ppk file is using an old unsupported format (#{format})" if format < MINIMUM_FORMAT
+
             encryption_type = reader.field('Encryption')
             @comment = reader.field('Comment')
             @public_blob = reader.blob('Public')
-            encrypted_private_blob = reader.blob('Private')
-            private_mac = reader.field('Private-MAC')
-            [encryption_type, encrypted_private_blob, private_mac]
-          end
 
-          if encryption_type == 'none'
-            passphrase = nil
-            @private_blob = encrypted_private_blob
-          else
-            raise FormatError, "The ppk file is encrypted with #{encryption_type}, which is not supported" unless encryption_type == DEFAULT_ENCRYPTION_TYPE
-            raise ArgumentError, 'The ppk file is encrypted, a passphrase must be supplied' unless passphrase
-
-            # PuTTY uses a zero IV.
-            cipher = ::OpenSSL::Cipher::AES.new(256, :CBC)
-            cipher.decrypt
-            cipher.key = generate_encryption_key(passphrase, cipher.key_len)
-            cipher.padding = 0
-            @private_blob = cipher.update(encrypted_private_blob) + cipher.final
-          end
 
-          expected_private_mac = compute_private_mac(passphrase, encryption_type, @private_blob)
+            if encryption_type == 'none'
+              passphrase = nil
+              mac_key = derive_keys(format).first
+              @private_blob = reader.blob('Private')
+            else
+              raise FormatError, "The ppk file is encrypted with #{encryption_type}, which is not supported" unless encryption_type == DEFAULT_ENCRYPTION_TYPE
+              raise ArgumentError, 'The ppk file is encrypted, a passphrase must be supplied' unless passphrase
+
+              argon2_params = if format >= 3
+                type = get_argon2_type(reader.field('Key-Derivation'))
+                memory = reader.unsigned_integer('Argon2-Memory', maximum: 2**32)
+                passes = reader.unsigned_integer('Argon2-Passes', maximum: 2**32)
+                parallelism = reader.unsigned_integer('Argon2-Parallelism', maximum: 2**32)
+                salt = reader.field('Argon2-Salt')
+                unless salt =~ /\A(?:[0-9a-fA-F]{2})+\z/
+                  raise FormatError, "Expected the Argon2-Salt field to be a hex string, but found #{salt}"
+                end
+
+                Argon2Params.new(type: type, memory: memory, passes: passes, parallelism: parallelism, salt: [salt].pack('H*'))
+              end
+
+              cipher = ::OpenSSL::Cipher::AES.new(256, :CBC)
+              cipher.decrypt
+              mac_key, cipher.key, cipher.iv = derive_keys(format, cipher, passphrase, argon2_params)
+              cipher.padding = 0
+              encrypted_private_blob = reader.blob('Private')
+
+              @private_blob = if encrypted_private_blob.bytesize > 0
+                partial = cipher.update(encrypted_private_blob)
+                final = cipher.final
+                partial + final
+              else
+                encrypted_private_blob
+              end
+            end
 
-          unless private_mac == expected_private_mac
-            raise ArgumentError, 'Incorrect passphrase supplied' if passphrase
-            raise FormatError, "Invalid Private MAC (expected #{expected_private_mac}, but found #{private_mac})"
+            private_mac = reader.field('Private-MAC')
+            expected_private_mac = compute_private_mac(format, mac_key, encryption_type, @private_blob)
+
+            unless private_mac == expected_private_mac
+              raise ArgumentError, 'Incorrect passphrase supplied' if passphrase
+              raise FormatError, "Invalid Private MAC (expected #{expected_private_mac}, but found #{private_mac})"
+            end
           end
         end
       end
 
-      # Saves this PuTTY private key instance to a .ppk file.
+      # Writes this PuTTY private key instance to a .ppk file or `IO`-like
+      # instance.
+      #
+      # To write to a file, set `path_or_io` to the file path, either as a
+      # `String` or a `Pathname`. To write to an `IO`-like instance set
+      # `path_or_io` to the instance. The instance must respond to `#write`.
+      # `#binmode` will be called before writing if supported by the instance.
+      #
+      # If a file with the given path already exists, it will be overwritten.
       #
       # The {#algorithm}, {#private_blob} and {#public_blob} attributes must
       # have been set before calling {#save}.
       #
-      # @param path [Object] The path to write to. If a file already exists, it
-      #   will be overwritten.
+      # @param path_or_io [Object] The path to write to as a `String` or
+      #   `Pathname`, or an `IO`-like instance to write to.
       # @param passphrase [String] Set `passphrase` to encrypt the .ppk file
       #   using the specified passphrase. Leave as `nil` to create an
       #   unencrypted .ppk file.
       # @param encryption_type [String] The encryption algorithm to use.
       #   Defaults to and currently only supports `'aes256-cbc'`.
       # @param format [Integer] The format of .ppk file to create. Defaults to
-      #   and currently only supports `2`.
+      #   `2`. Supports `2` and `3`.
+      # @param argon2_params [Argon2Params] The parameters to use with Argon2
+      #   to derive the encryption key, initialization vector and MAC key when
+      #   saving an encrypted format 3 .ppk file.
       #
       # @return [Integer] The number of bytes written to the file.
       #
@@ -131,52 +201,73 @@ module PuTTY
       # @raise [ArgumentError] If `path` is nil.
       # @raise [ArgumentError] If a passphrase has been specified and
       #   `encryption_type` is not `'aes256-cbc'`.
-      # @raise [ArgumentError] If `format` is not `2`.
+      # @raise [ArgumentError] If `format` is not `2` or `3`.
+      # @raise [ArgumentError] If `argon2_params` is `nil`, a passphrase has
+      #   been specified and `format` is `3`.
       # @raise [Errno::ENOENT] If a directory specified by `path` does not
       #   exist.
-      def save(path, passphrase = nil, encryption_type: DEFAULT_ENCRYPTION_TYPE, format: DEFAULT_FORMAT)
+      # @raise [LoadError] If saving an encrypted format 3 .ppk file and
+      #   libargon2 could not be loaded.
+      # @raise [Argon2Error] If saving an encrypted format 3 .ppk file and
+      #   libargon2 reported an error hashing the passphrase.
+      def save(path_or_io, passphrase = nil, encryption_type: DEFAULT_ENCRYPTION_TYPE, format: DEFAULT_FORMAT, argon2_params: DEFAULT_ARGON2_PARAMS)
         raise InvalidStateError, 'algorithm must be set before calling save' unless @algorithm
         raise InvalidStateError, 'public_blob must be set before calling save' unless @public_blob
         raise InvalidStateError, 'private_blob must be set before calling save' unless @private_blob
 
+        raise ArgumentError, 'An output path or io instance must be specified' unless path_or_io
+
         passphrase = nil if passphrase && passphrase.to_s.empty?
-        encryption_type = 'none' unless passphrase
 
-        raise ArgumentError, 'An output path must be specified' unless path
+        raise ArgumentError, 'A format must be specified' unless format
+        raise ArgumentError, "Unsupported format: #{format}" unless format >= MINIMUM_FORMAT && format <= MAXIMUM_FORMAT
 
         if passphrase
           raise ArgumentError, 'An encryption_type must be specified if a passphrase is specified' unless encryption_type
           raise ArgumentError, "Unsupported encryption_type: #{encryption_type}" unless encryption_type == DEFAULT_ENCRYPTION_TYPE
-        end
-
-        raise ArgumentError, 'A format must be specified' unless format
-        raise ArgumentError, "Unsupported format: #{format}" unless format == DEFAULT_FORMAT
-
-        padded_private_blob = @private_blob
+          raise ArgumentError, 'argon2_params must be specified if a passphrase is specified with format 3' unless format < 3 || argon2_params
 
-        if passphrase
-          # Pad using an SHA-1 hash of the unpadded private blob in order to
-          # prevent an easily known plaintext attack on the last block.
           cipher = ::OpenSSL::Cipher::AES.new(256, :CBC)
           cipher.encrypt
-          padding_length = cipher.block_size - (padded_private_blob.bytesize % cipher.block_size)
-          padded_private_blob += ::OpenSSL::Digest::SHA1.new(padded_private_blob).digest[0, padding_length]
-
-          # PuTTY uses a zero IV.
-          cipher.key = generate_encryption_key(passphrase, cipher.key_len)
+          mac_key, cipher.key, cipher.iv, kdf_params = derive_keys(format, cipher, passphrase, argon2_params)
           cipher.padding = 0
-          encrypted_private_blob = cipher.update(padded_private_blob) + cipher.final
+
+          # Pad using an SHA-1 hash of the unpadded private blob in order to
+          # prevent an easily known plaintext attack on the last block.
+          padding_length = cipher.block_size - ((@private_blob.bytesize - 1) % cipher.block_size) - 1
+          padded_private_blob = @private_blob
+          padded_private_blob += ::OpenSSL::Digest::SHA1.new(@private_blob).digest.byteslice(0, padding_length) if padding_length > 0
+
+          encrypted_private_blob = if padded_private_blob.bytesize > 0
+            partial = cipher.update(padded_private_blob)
+            final = cipher.final
+            partial + final
+          else
+            padded_private_blob
+          end
         else
-          encrypted_private_blob = private_blob
+          encryption_type = 'none'
+          mac_key = derive_keys(format).first
+          kdf_params = nil
+          padded_private_blob = @private_blob
+          encrypted_private_blob = padded_private_blob
         end
 
-        private_mac = compute_private_mac(passphrase, encryption_type, padded_private_blob)
+        private_mac = compute_private_mac(format, mac_key, encryption_type, padded_private_blob)
 
-        Writer.open(path) do |writer|
-          writer.field('PuTTY-User-Key-File-2', @algorithm)
+        Writer.open(path_or_io) do |writer|
+          writer.field("PuTTY-User-Key-File-#{format}", @algorithm)
           writer.field('Encryption', encryption_type)
           writer.field('Comment', @comment)
           writer.blob('Public', @public_blob)
+          if kdf_params
+            # Only Argon2 is currently supported.
+            writer.field('Key-Derivation', "Argon2#{kdf_params.type}")
+            writer.field('Argon2-Memory', kdf_params.memory)
+            writer.field('Argon2-Passes', kdf_params.passes)
+            writer.field('Argon2-Parallelism', kdf_params.parallelism)
+            writer.field('Argon2-Salt', kdf_params.salt.unpack('H*').first)
+          end
           writer.blob('Private', encrypted_private_blob)
           writer.field('Private-MAC', private_mac)
         end
@@ -184,13 +275,188 @@ module PuTTY
 
       private
 
-      # Generates an encryption key of the specified length from a passphrase.
+      # Returns the Argon2 type (`:d`, `:i` or `:id`) corresponding to the value
+      # of the Key-Derivation field in the .ppk file.
+      #
+      # @param key_derivation [String] The value of the Key-Derivation field.
+      #
+      # @return [Symbol] The Argon2 type.
+      #
+      # @raise [FormatError] If `key_derivation` is unrecognized.
+      def get_argon2_type(key_derivation)
+        unless key_derivation =~ /\AArgon2(d|id?)\z/
+          raise FormatError, "Unrecognized key derivation type: #{key_derivation}"
+        end
+
+        $1.to_sym
+      end
+
+      # Derives the MAC key, encryption key and initialization vector from the
+      # passphrase (if the file is encrypted).
+      #
+      # @param format [Integer] The format of the .ppk file.
+      # @param cipher [OpenSSL::Cipher] The cipher being used to encrypt or
+      #   decrypt the .ppk file or `nil` if not encrypted.
+      # @param passphrase [String] The passphrase used in the derivation or
+      #   `nil` if the .ppk file is not encrypted. The raw bytes of the
+      #   passphrase are used in the derivation.
+      # @param argon2_params [Argon2Params] Parameters used with the Argon2 hash
+      #   function. May be `nil` if the .ppk file is not encrypted or `format`
+      #   is less than 3.
+      #
+      # @return [Array<String, String, String, Argon2Params>] The MAC key,
+      #   encryption key, initialization vector and final Argon2 parameters.
+      #   The encryption key and initialization vector will be `nil` if `cipher`
+      #   is `nil`. The final Argon2 parameters will only be set if `format` is
+      #   greater than or equal to 3 and `cipher` is not nil. The final Argon2
+      #   parameters will differ from `argon2_params` if the salt and passes
+      #   options were left unspecified.
+      #
+      # @raise [LoadError] If `format` is at least 3, `cipher` is specified and
+      #   libargon2 could not be loaded.
+      # @raise [Argon2Error] If `format` is at least 3, `cipher` is specified
+      #   and libargon2 reported an error hashing the passphrase.
+      def derive_keys(format, cipher = nil, passphrase = nil, argon2_params = nil)
+        if format >= 3
+          return derive_format_3_keys(cipher, passphrase, argon2_params) if cipher
+
+          # An empty string should work for the MAC, but ::OpenSSL::HMAC fails
+          # when used with OpenSSL 3:
+          #
+          #   EVP_PKEY_new_mac_key: malloc failure (OpenSSL::HMACError).
+          #
+          # See https://github.com/ruby/openssl/pull/538 and
+          # https://github.com/openssl/openssl/issues/13089.
+          #
+          # Ruby 3.1.3 should contain the workaround from ruby/openssl PR 538.
+          #
+          # Use "\0" as the MAC key for a workaround for Ruby < 3.1.3.
+          return ["\0".b, nil, nil, nil]
+        end
+
+        mac_key = derive_format_2_mac_key(passphrase)
+
+        if cipher
+          key = derive_format_2_encryption_key(passphrase, cipher.key_len)
+          iv = "\0".b * cipher.iv_len
+        else
+          key = nil
+          iv = nil
+        end
+
+        [mac_key, key, iv, nil]
+      end
+
+      # Initializes the Argon2 salt if required, determines the number of passes
+      # to use to meet the time requirement unless preset and then derives the
+      # MAC key, encryption key and initalization vector.
+      #
+      # @param cipher [OpenSSL::Cipher] The cipher being used to encrypt or
+      #   decrypt the .ppk file.
+      # @param passphrase [String] The passphrase used in the derivation. The
+      #   raw bytes of the passphrase are used in the derivation.
+      # @param argon2_params [Argon2Params] Parameters used with the Argon2 hash
+      #   function.
+      #
+      # @return [Array<String, String, String, Argon2Params>] The MAC key,
+      #   encryption key, initialization vector and final Argon2 parameters.
+      #   The encryption key and initialization vector will be `nil` if `cipher`
+      #   is `nil`. The final Argon2 parameters will differ from `argon2_params`
+      #   if the salt and passes options were left unspecified.
+      #
+      # @raise [LoadError] If libargon2 could not be loaded.
+      # @raise [Argon2Error] If libargon2 reported an error hashing the
+      #   passphrase.
+      def derive_format_3_keys(cipher, passphrase, argon2_params)
+        # Defer loading of libargon2 to avoid a mandatory dependency.
+        require_relative 'libargon2'
+
+        salt = argon2_params.salt || ::OpenSSL::Random.random_bytes(16)
+        passphrase_ptr = pointer_for_bytes(passphrase)
+        salt_ptr = pointer_for_bytes(salt)
+        hash_ptr = FFI::MemoryPointer.new(:char, cipher.key_len + cipher.iv_len + FORMAT_3_MAC_KEY_LENGTH)
+        begin
+          passes = argon2_params.passes
+          if passes
+            argon2_hash(argon2_params.type, argon2_params.passes, argon2_params.memory, argon2_params.parallelism, passphrase_ptr, salt_ptr, hash_ptr)
+          else
+            # Only require the time taken to be approximately correct. Scale up
+            # geometrically using Fibonacci numbers (as per PuTTY's
+            # implementation).
+            prev_passes = 1
+            passes = 1
+
+            loop do
+              start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              argon2_hash(argon2_params.type, passes, argon2_params.memory, argon2_params.parallelism, passphrase_ptr, salt_ptr, hash_ptr)
+              elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000
+              break if (elapsed >= argon2_params.desired_time)
+              hash_ptr.clear
+              new_passes = passes + prev_passes
+              break if new_passes > 2**32 # maximum allowed by argon2_hash parameter data type
+              prev_passes, passes = passes, new_passes
+            end
+          end
+
+          passphrase_ptr.clear
+          key = hash_ptr.get_bytes(0, cipher.key_len)
+          iv = hash_ptr.get_bytes(cipher.key_len, cipher.iv_len)
+          mac_key = hash_ptr.get_bytes(cipher.key_len + cipher.iv_len, FORMAT_3_MAC_KEY_LENGTH)
+          argon2_params = argon2_params.complete(passes, salt)
+          hash_ptr.clear
+          [mac_key, key, iv, argon2_params]
+        ensure
+          # Calling free isn't actually required, but this releases the memory
+          # sooner.
+          hash_ptr.free
+          salt_ptr.free
+          passphrase_ptr.free
+        end
+      end
+
+      # Creates an `FFI::MemoryPointer` containing the raw bytes from `string`
+      # without a null terminator.
+      #
+      # @param string [String] The bytes to use for the `FFI::MemoryPointer`.
+      #
+      # @return [FFI::MemoryPointer] A new `FFI::MemoryPointer` containing the
+      #   raw bytes from `string`.
+      def pointer_for_bytes(string)
+        FFI::MemoryPointer.new(:char, string.bytesize).tap do |ptr|
+          ptr.put_bytes(0, string)
+        end
+      end
+
+      # Calls the libargon2 `argon2_hash` function to obtain a raw hash using
+      # version 13 of the algorithm.
+      #
+      # @param type [Symbol] The variant of Argon2 to use. (`:d`, `:i` or
+      #   `:id`).
+      # @param iterations [Integer] The number of iterations to use.
+      # @param memory [Integer] Memory usage in kibibytes.
+      # @param passhrase [FFI::MemoryPointer] The passphrase.
+      # @param salt [FFI::MemoryPointer] The salt.
+      # @param hash [FFI::MemoryPointer] A buffer to write the raw hash to.
+      #
+      # @raise [Argon2Error] If `argon2_hash` returns an error.
+      def argon2_hash(type, iterations, memory, parallelism, passphrase, salt, hash)
+        res = Libargon2.argon2_hash(iterations, memory, parallelism,
+          passphrase, passphrase.size, salt, salt.size,
+          hash, hash.size, FFI::Pointer::NULL, 0, type, :version_13)
+
+        unless res == Libargon2::ARGON2_OK
+          raise Argon2Error.new(res, Libargon2.argon2_error_message(res))
+        end
+      end
+
+      # Derives an encryption key of the specified length from a passphrase for
+      # use in format 2 files.
       #
       # @param passphrase [String] The passphrase to use.
       # @param key_length [Integer] The length of the desired key in bytes.
       #
-      # @return [String] The generated key.
-      def generate_encryption_key(passphrase, key_length)
+      # @return [String] The derived encryption key.
+      def derive_format_2_encryption_key(passphrase, key_length)
         key = String.new
         key_digest = ::OpenSSL::Digest::SHA1.new
         iteration = 0
@@ -209,47 +475,72 @@ module PuTTY
         key[0, key_length]
       end
 
+      # Derives a MAC key from a passphrase for use in format 2 files.
+      #
+      # @param passphrase [String] The passphrase to use or `nil` if not
+      #   encrypted.
+      #
+      # @return [String] The derived MAC key.
+      def derive_format_2_mac_key(passphrase)
+        key = ::OpenSSL::Digest::SHA1.new
+        key.update(FORMAT_2_MAC_KEY)
+        key.update(passphrase) if passphrase
+        key.digest
+      end
+
       # Computes the value of the Private-MAC field given the passphrase,
       # encryption type and padded private blob (the value of the private blob
       # after padding bytes have been appended prior to encryption).
       #
-      # @param passphrase [String] The encryption passphrase.
+      # @param format [Integer] The format of the .ppk file.
+      # @param mac_key [String] The HMAC key.
       # @param encryption_type [String] The value of the Encryption field.
       # @param padded_private_blob [String] The private blob after padding bytes
       #   have been appended prior to encryption.
       #
       # @return [String] The computed private MAC.
-      def compute_private_mac(passphrase, encryption_type, padded_private_blob)
-        key = ::OpenSSL::Digest::SHA1.new
-        key.update(MAC_KEY)
-        key.update(passphrase) if passphrase
+      def compute_private_mac(format, mac_key, encryption_type, padded_private_blob)
+        digest = format <= 2 ? ::OpenSSL::Digest::SHA1 : ::OpenSSL::Digest::SHA256
         data = Util.ssh_pack(@algorithm, encryption_type, @comment || '', @public_blob, padded_private_blob)
-        ::OpenSSL::HMAC.hexdigest(::OpenSSL::Digest::SHA1.new, key.digest, data)
+        ::OpenSSL::HMAC.hexdigest(digest.new, mac_key, data)
       end
 
       # Handles reading .ppk files.
       #
       # @private
       class Reader
-        # Opens a .ppk file for reading, creates a new instance of `Reader` and
-        # yields it to the caller.
+        # Opens a .ppk file for reading (or uses the provided `IO`-like
+        # instance), creates a new instance of `Reader` and yields it to the
+        # caller.
         #
-        # @param path [Object] The path of the .ppk file to be read.
+        # @param path_or_io [Object] The path of the .ppk file to be read or an
+        #   `IO`-like object.
         #
         # @return [Object] The result of yielding to the caller.
         #
         # raise [Errno::ENOENT] If the file specified by `path` does not exist.
-        def self.open(path)
-          File.open(path.to_s, 'rb') do |file|
-            yield Reader.new(file)
+        def self.open(path_or_io)
+          if path_or_io.kind_of?(String) || path_or_io.kind_of?(Pathname)
+            File.open(path_or_io.to_s, 'rb') do |file|
+              yield Reader.new(file)
+            end
+          else
+            path_or_io.binmode if path_or_io.respond_to?(:binmode)
+
+            unless path_or_io.respond_to?(:getbyte)
+              path_or_io = GetbyteIo.new(path_or_io)
+            end
+
+            yield Reader.new(path_or_io)
           end
         end
 
-        # Initializes a new {Reader} with an {IO} to read from.
+        # Initializes a new {Reader} with an `IO`-like instance to read from.
         #
-        # @param file [IO] The file to read from.
+        # @param file [Object] The `IO`-like instance to read from.
         def initialize(file)
           @file = file
+          @consumed_byte = nil
         end
 
         # Reads the next field from the file.
@@ -266,6 +557,46 @@ module PuTTY
           line.byteslice(name.bytesize + 2, line.bytesize - name.bytesize - 2)
         end
 
+        # Reads the next field from the file.
+        #
+        # @param name_regexp [Regexp] A `Regexp` that matches the expected field
+        #   name.
+        #
+        # @return [String] The value of the field if the regular expression has
+        #   no captures.
+        # @return [Array] An array containing the regular expression captures as
+        #   the first elements and the value of the field as the last element.
+        #
+        # @raise [FormatError] If the current position in the file was not the
+        #   start of a field with the expected name.
+        def field_matching(name_regexp)
+          line = read_line
+          line_regexp = Regexp.new("\\A#{name_regexp.source}: ", name_regexp.options)
+          match = line_regexp.match(line)
+          raise FormatError, "Expected field matching #{name_regexp}, but found #{line}" unless match
+          prefix = match[0]
+          value = line.byteslice(prefix.bytesize, line.bytesize - prefix.bytesize)
+          captures = match.captures
+          captures.empty? ? value : captures + [value]
+        end
+
+        # Reads the next field from the file as an unsigned integer.
+        #
+        # @param name [String] The expected field name.
+        #
+        # @return [Integer] The value of the field.
+        #
+        # @raise [FormatError] If the current position in the file was not the
+        #   start of a field with the expected name.
+        # @raise [FormatError] If the field did not contain a positive integer.
+        def unsigned_integer(name, maximum: nil)
+          value = field(name)
+          value = value =~ /\A[0-9]+\z/ && value.to_i
+          raise FormatError, "Expected field #{name} to contain an unsigned integer value, but found #{value}" unless value
+          raise FormatError, "Expected field #{name} to have a maximum of #{maximum}, but found #{value}" if maximum && value > maximum
+          value
+        end
+
         # Reads a blob from the file consisting of a Lines field whose value
         # gives the number of Base64 encoded lines in the blob.
         #
@@ -276,28 +607,68 @@ module PuTTY
         # @raise [FormatError] If the value of the Lines field is not a
         #   positive integer.
         def blob(name)
-          lines = field("#{name}-Lines")
-          raise FormatError, "Invalid value for #{name}-Lines" unless lines =~ /\A\d+\z/
-          lines.to_i.times.map { read_line }.join("\n").unpack('m48').first
+          lines = unsigned_integer("#{name}-Lines")
+          lines.times.map { read_line }.join("\n").unpack('m48').first
         end
 
         private
 
-        # Reads a single new-line (\n or \r\n) terminated line from the file,
-        # removing the new-line character.
+        # Reads a single new-line (\n, \r\n or \r) terminated line from the
+        # file, removing the new-line character.
         #
         # @return [String] The line.
         #
         # @raise [FormatError] If the end of file was detected before reading a
         #   line.
         def read_line
-          @file.readline("\n").chomp("\n")
-        rescue EOFError
+          line = ''.b
+
+          if @consumed_byte
+            line << @consumed_byte
+            @consumed_byte = nil
+          end
+
+          while byte = @file.getbyte
+            return line if byte == 0x0a
+
+            if byte == 0x0d
+              byte = @file.getbyte
+              return line if !byte || byte == 0x0a
+              @consumed_byte = byte
+              return line
+            end
+
+            line << byte
+          end
+
+          return line if line.bytesize > 0
           raise FormatError, 'Truncated ppk file detected'
         end
       end
       private_constant :Reader
 
+      # Wraps an `IO`-like instance, providing an implementation of `#getbyte`.
+      # Allows reading from `IO`-like instances that only provide `#read`.
+      class GetbyteIo
+        # Initializes a new {GetbyteIO} with the given `IO`-like instance.
+        #
+        # @param io [Object] An `IO`-like instance.
+        def initialize(io)
+          @io = io
+          @outbuf = ' '.b
+        end
+
+        # Gets the next 8-bit byte (0..255) from the `IO`-like instance.
+        #
+        # @return [Integer] the next byte or `nil` if the end of the stream has
+        #   been reached.
+        def getbyte
+          s = @io.read(1, @outbuf)
+          s && s.getbyte(0)
+        end
+      end
+      private_constant :GetbyteIo
+
       # Handles writing .ppk files.
       #
       # @private
@@ -307,24 +678,31 @@ module PuTTY
         # @return [Integer] The number of bytes that have been written.
         attr_reader :bytes_written
 
-        # Opens a .ppk file for writing, creates a new instance of `Writer` and
-        # yields it to the caller.
+        # Opens a .ppk file for writing (or uses the provided `IO`-like
+        # instance), creates a new instance of `Writer` and yields it to the
+        # caller.
         #
-        # @param path [Object] The path of the .ppk file to be written.
+        # @param path_or_io [Object] The path of the .ppk file to be written or
+        #   an `IO`-like instance.
         #
         # @return [Object] The result of yielding to the caller.
         #
         # @raise [Errno::ENOENT] If a directory specified by `path` does not
         #   exist.
-        def self.open(path)
-          File.open(path.to_s, 'wb') do |file|
-            yield Writer.new(file)
+        def self.open(path_or_io)
+          if path_or_io.kind_of?(String) || path_or_io.kind_of?(Pathname)
+            File.open(path_or_io.to_s, 'wb') do |file|
+              yield Writer.new(file)
+            end
+          else
+            path_or_io.binmode if path_or_io.respond_to?(:binmode)
+            yield Writer.new(path_or_io)
           end
         end
 
-        # Initializes a new {Writer} with an {IO} to write to.
+        # Initializes a new {Writer} with an `IO`-like instance to write to.
         #
-        # @param file [IO] The file to write to.
+        # @param file [Object] The `IO`-like instance to write to.
         def initialize(file)
           @file = file
           @bytes_written = 0
@@ -333,7 +711,7 @@ module PuTTY
         # Writes a field to the file.
         #
         # @param name [String] The field name.
-        # @param value [String] The field value.
+        # @param value [Object] The field value.
         def field(name, value)
           write(name)
           write(': ')
@@ -358,9 +736,9 @@ module PuTTY
 
         private
 
-        # Writes a line separator to the file (\r\n on all platforms).
+        # Writes a line separator to the file (\n on all platforms).
         def write_line
-          write("\r\n")
+          write("\n")
         end
 
         # Writes a string to the file.