putty-key 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ee468e63692d4e452273f75c0e2349f451992fa906901f8856685c8c8f2bf82
-  data.tar.gz: 4aafcf168d89410aae4e6f513a10e6fb3261c4a88493ca88125a1ea251cc6721
+  metadata.gz: 0e875308cd1e8bd154bb40ceccf856a1b91cfa74e1858c89b006735016980c10
+  data.tar.gz: 9306636667b1864c570bc467837e44e3d2490b965d4c3493ff1abe853832d419
 SHA512:
-  metadata.gz: 67187df6dd956d5067b3a97f35fe53fbb35698f788c5a08f6fd6bf42cc20afcb910fab6773f8af24ac6d53d6f9bd0c23737e47d683921147e9453296d3eed32d
-  data.tar.gz: 7ff5c7f235975206b17da9be813221c4d24e9706e036ef4fc32ed097cfa4ce52deeb11cd9acfc68c218b0e6b7f68d07a54155e81738acd3bf05ca26f75921f03
+  metadata.gz: 52426f86621cff16b7a55901144e987f8ecc8478c7204511449d8de3d19258c60f472deb98e85996d39f9a3a197e2a2832095d01e09e710454f30d00c99af820
+  data.tar.gz: acb9f8986b8c42e554e14d54d11cb6d6bde103256780dd31a81e4b828e6109b40d03b19460479868334028a9534a05eb729d04db555678c3db7a0a12651d9b32

data/CHANGES.md

@@ -1,5 +1,21 @@
 # Changes #
 
+## 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

@@ -14,10 +14,4 @@ group :test do
   # coveralls_reborn is maintained, but requires Ruby >= 2.3.
   gem 'coveralls', '~> 0.8', 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.
-  #
-  # Limit to earlier versions on Ruby 1.9.
-  gem 'json', '< 2.3.0', require: false if RUBY_VERSION < '2.0'
 end

data/LICENSE

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

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 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.
+  # PuTTY::Key is a 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
@@ -20,6 +19,7 @@ module PuTTY
 end
 
 require_relative 'key/version'
+require_relative 'key/argon2_params'
 require_relative 'key/error'
 require_relative 'key/util'
 require_relative 'key/ppk'

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

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,176 @@ 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
+          return [''.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 +463,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 format [Integer] The format of the .ppk file.
       # @param passphrase [String] The encryption passphrase.
       # @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 +545,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 +595,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 +666,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 +699,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 +724,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.