SshSig - SSH signature verification in pure ruby

SshSig is a Ruby gem which can be used to verify signatures signed created by ssh-keygen. This capability was first added in OpenSSH 8.0 allows SSH keys to be used for GPG-like signing capabilities, including signing git commits.

Installation

Add this line to your application's Gemfile:

gem 'ssh_sig'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ssh_sig

Usage

Version 1 of the SSH signature format supports ed25519 and rsa keys. It is recommended that you use ed25519 over rsa where possible (ssh-keygen -t ed25519).

In order to verify a signature you need:

  1. The public key of the sender
  2. The signature file
  3. The message to be verified.
require 'ssh_sig'

armored_pubkey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILXPkJPI4TMFWZP4xRBQjNeizUG99KuZCt9G23rX48kz"

blob = ::SshSig::Blob.from_armor(
  "  -----BEGIN SSH SIGNATURE-----\n  U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgtc+Qk8jhMwVZk/jFEFCM16LNQb\n  30q5kK30bbetfjyTMAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx\n  OQAAAECJITeYJIlEeydsCTh1DkfdhlDJFBa73ojfWe0MbrIzoJKd9THd9WeQrhygSRGsNG\n  cU/stk3/919nykg67yG2gN\n  -----END SSH SIGNATURE-----\n  EOF\n)\n\nmessage = \"This message was definitely sent by Brian Williams\"\n\nvalid = ::SshSig::Verifier\n  .from_armored_pubkey(armored_pubkey)\n  .verify(blob, message)\n\nif valid\n  puts 'Signature is valid'\nelse\n  puts 'Signature is not valid'\nend\n"

Signatures can be created using ssh-keygen -Y sign -n file -f ~/.ssh/ed_25519 message.txt and will be outputted in message.txt.sig.

Public keys can be found in a variety of places, including:

  • Your ~/.ssh/id_<alg>.pub file
  • authorized_keys files on servers
  • https://gitlab.com/<username>.keys
  • https://github.com/<username>.keys

The SshSig::Verifier#from_gitlab and SshSig::Verifier#from_github methods are provided to automatically load public keys from the respective <username>.keys urls.

require 'ssh_sig'

blob = ::SshSig::Blob.from_armor(
  "  -----BEGIN SSH SIGNATURE-----\n  U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgtc+Qk8jhMwVZk/jFEFCM16LNQb\n  30q5kK30bbetfjyTMAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx\n  OQAAAECJITeYJIlEeydsCTh1DkfdhlDJFBa73ojfWe0MbrIzoJKd9THd9WeQrhygSRGsNG\n  cU/stk3/919nykg67yG2gN\n  -----END SSH SIGNATURE-----\n  EOF\n)\n\nmessage = 'This message was definitely sent by Brian Williams'\n\nvalid = ::SshSig::Verifier\n  .from_gitlab('bwill')\n  .verify(blob, message)\n\nif valid\n  puts 'Signature is valid'\nelse\n  puts 'Signature is not valid'\nend\n"

Is it safe to re-purpose SSH keys for signing?

Yes. The SSH signature protocol is designed to be resistant to cross-protocol attacks, where signatures created for one purpose (i.e. signing a git commit), may be re-used for another purpose (i.e. authenticating to a server). It does this using the magic pre-amble (to differentiate between messages signed by ssh-keygen and messages used for SSH authentication) and namespaces (to differentiate between messages signed by ssh-keygen but used for different purposes). This causes identical messages to produce different signatures for each different protocol.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ssh_sig. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.