PuTTY::Key

Gem Version Build Status Build status Coverage Status

PuTTY::Key is a pure-Ruby implementation of the PuTTY private key (ppk) format, handling reading and writing .ppk files. It includes a refinement to Ruby's OpenSSL library to add support for converting DSA, EC and RSA private keys to and from PuTTY private key files. This allows OpenSSH ecdsa, ssh-dss and ssh-rsa private keys to be converted to and from PuTTY's private key format.

Installation

To install the PuTTY::Key gem, run the following command:

gem install putty-key

To add PuTTY::Key as a Bundler dependency, add the following line to your Gemfile:

gem 'putty-key'

Compatibility

PuTTY::Key is compatible with Ruby MRI 2.1.0+ and JRuby 9.1.0.0+.

Usage

To use PuTTY::Key, it must first be loaded with:

require 'putty/key'

The included refinement to Ruby's OpenSSL library can then either be activated in the lexical scope (file, class or module) where it will be used with:

using PuTTY::Key

or installed globally by calling:

PuTTY::Key.global_install

The following sections give examples of how PuTTY::Key can be used.

Converting a .pem formatted key file to an unencrypted .ppk file

require 'openssl'
require 'putty/key'
using PuTTY::Key    # or PuTTY::Key.global_install

pem = File.read('key.pem', mode: 'rb')
pkey = OpenSSL::PKey.read(pem)
ppk = pkey.to_ppk
ppk.comment = 'Optional comment'
ppk.save('key.ppk')

Generating a new RSA key and saving it as an encrypted .ppk file

require 'openssl'
require 'putty/key'
using PuTTY::Key    # or PuTTY::Key.global_install

rsa = OpenSSL::PKey::RSA.generate(2048)
ppk = rsa.to_ppk
ppk.comment = 'RSA 2048'
ppk.save('rsa.ppk', 'Passphrase for encryption')

Converting an unencrypted .ppk file to .pem format

require 'openssl'
require 'putty/key'
using PuTTY::Key    # or PuTTY::Key.global_install

ppk = PuTTY::Key::PPK.new('key.ppk')
pkey = OpenSSL::PKey.from_ppk(ppk)
pem = pkey.to_pem
File.write('key.pem', pem, mode: 'wb')

Decrypting a .ppk file and re-saving it without encryption

require 'putty/key'

ppk = PuTTY::Key::PPK.new('rsa.ppk', 'Passphrase for encryption')
ppk.save('rsa-plain.ppk')

API Documentation

API documentation for PuTTY::Key is available on RubyDoc.info.

License

PuTTY::Key is distributed under the terms of the MIT license. A copy of this license can be found in the included LICENSE file.

GitHub Project

Source code, release information and the issue tracker can be found on the PuTTY::Key GitHub project page.