Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


Expand gem security build/install instructions; add checksum #70

merged 7 commits into from

3 participants


For review, @drbrain

  • section demarcation
  • syntax highlighting
  • verbosity / correctness of examples

cc @YorickPeterse
cc @grant-olson
cc @tarcieri

@bf4 bf4 referenced this pull request in grant-olson/rubygems-openpgp

Website inaccessible in Chrome, ssl cert mismatch #34


Re: YorickPeterse/ruby-lint#72 (comment)

I do not think that the rubygems PGP CA is worth mentioning/using. Although the idea in itself was interesting it was of little value over the existing key server infrastructure out there. Having a single developer act as a CA is no more secure than a group of developers that share mutual trust.

Whether it's worth mentioning the PGP plugin is also something I'm not sure about. This isn't per definition because PGP is back but because unless it's enforced (that is, RubyGems enforces signed packages only) nobody will use it. In fact, although I do sign ruby-lint myself I've yet to see a single other Gem do it.

Personally I'm considering to stop signing Gems using PGP as based on my own use and the use of others I consider it no more secure than providing a list of SHA1 checksums in a Git repository.

The built-in certificate signing system is definitely worth mentioning although I don't think it solves anything. Users are required to set trust levels, put all kinds of extra stuff in Gemspecs and due to it not being enforced it will only be a massive pain.

For example, if the Rails maintainers decide to sign rails then unless every Gem that it depends on is also signed it's still fairly useless. One of those Gems is still unverified and depending on your trust settings the entire install will fail. Although the latter makes sense from a security point of view (that's the point of said trust level) I'm 95% sure that the first developer that is not a security expert will just turn the trust system off the moment they experience a problem like this.

OK so I kinda went off topic there. To cut a long story short: I don't think mentioning GPG is worth it unless it becomes a standard, which it probably never will due to it not being available on every platform. For certificate signing it's important to state both the upsides and downsides as well as why one should do it in the first place. Just listing a bunch of commands isn't going to get Average Joe or Average Alice to suddenly sign their Gems.


Thanks @YorickPeterse, @grant-olson was just giving me similar advice to abandon use of the ca until it gets official backing, and for any gems using openpgp, to ask users to trust keys on an individual basis, as he notes at the bottom of the stackdriver-ruby readme


This week employees of Square are working on adding TUF to RubyGems which will probably replace the existing signing code. It's not worth inclusion yet, though.


Ok, @drbrain @YorickPeterse @grant-olson what do you think of this?


There's a small typo:

For details, see dicussion with Grant Olson and Yorick Peterse.

should be

For details, see discussion with Grant Olson and Yorick Peterse.

@YorickPeterse Ha, thanks!


After a glance, it looks OK to me!

@bf4 bf4 merged commit e63a922 into from

Ok, merged. Still needs attention, but I think this is a marked improvement (thanks to all comments!)


I think the questions asked in #62 would be good content to add:

  1. How to report gem security issues to an author/ and
  2. How a gem author should publicize the gem security release. (very few seem to [ANN] on ruby-lang or check it)
@yous yous referenced this pull request in ruby-korea/rubygems-guides

Translate security #9

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 78 additions and 10 deletions.
  1. +78 −10
@@ -28,10 +28,11 @@ optionally lets you set a security policy, and you can verify the signing key
for a gem before you install it.
However, this method of securing gems is not widely used. It requires a number
-of manual steps on the part of the developer, and there is no well-established
-chain of trust for gem signing keys. Discussion of new signing models using
-X509 or OpenPGP is going on in the [rubygems-trust
-wiki]( and
+of [manual steps on the part of the developer](#building_gems), and there is no
+well-established chain of trust for gem signing keys. Discussion of new signing models such as
+X509 and OpenPGP is going on in the [rubygems-trust
+wiki](, the
+[RubyGems-Developers list]( and
in [IRC](irc:// The goal is to improve (or
replace) the signing system so that it is easy for authors and transparent for
@@ -39,29 +40,96 @@ users.
Using Gems
-* Install with a trust policy.
+Install with a trust policy.
* `gem install gemname -P HighSecurity`: All dependent gems must be signed and verified.
* `gem install gemname -P MediumSecurity`: All signed dependent gems must be verified.
* `bundle --trust-policy MediumSecurity`: Same as above, except Bundler only recognizes
the long `--trust-policy` flag, not the short `-P`.
-* Risks of being pwned, as described by [Benjamin Smith's Hacking with Gems talk](
+ * *Caveat*: Gem certificates are trusted globally, such that adding a cert.pem for one gem automatically trusts
+ all gems signed by that cert.
+Verify the checksum, if available
+ gem fetch gemname -v version
+ ruby -rdigest/sha2 -e "puts'gemname-version.gem'))
+Know the risks of being pwned, as described by [Benjamin Smith's Hacking with Gems talk](
Building Gems
-* Official: `gem cert`
+### Sign with: `gem cert`
+1) Create self-signed gem cert
+ cd ~/.ssh
+ gem cert --build
+ chmod 600 gem-p*
+- use the email address you specify in your gemspecs
+2) Configure gemspec with cert
+Add cert public key to your repository
+ cd /path/to/your/gem
+ mkdir certs
+ cp ~/.ssh/gem-public_cert.pem certs/yourhandle.pem
+ git add certs/yourhandle.pem
+Add cert paths to your gemspec
+ s.cert_chain = ['certs/yourhandle.pem']
+ s.signing_key = File.expand_path("~/.ssh/gem-private_key.pem") if $0 =~ /gem\z/
+3) Add your own cert to your approved list, just like anyone else
+ gem cert --add certs/yourhandle.pem
+4) Build gem and test that you can install it
+ gem build gemname.gemspec
+ gem install gemname-version.gem -P HighSecurity
+ # or -P MediumSecurity if your gem depends on unsigned gems
+5) Example text for installation documentation
+> MetricFu is cryptographically signed. To be sure the gem you install hasn't been tampered with:
+> Add my public key (if you haven't already) as a trusted certificate
+> `gem cert --add <(curl -Ls`
+> `gem install metric_fu -P MediumSecurity`
+> The MediumSecurity trust profile will verify signed gems, but allow the installation of unsigned dependencies.
+> This is necessary because not all of MetricFu's dependencies are signed, so we cannot use HighSecurity.
+### Include checksum of released gems in your repository
- * [How to cryptographically sign your RubyGem]( - Step-by-step guide
+ require 'digest/sha2'
+ built_gem_path = 'pkg/gemname-version.gem'
+ checksum =
+ checksum_path = 'checksum/gemname-version.gem.sha512'
+, 'w' ) {|f| f.write(checksum) }
+ # add and commit 'checksum_path'
-* Alternative: [Rubygems OpenPGP signing](, [gem](
+### Not Recommended: OpenPGP signing is [not recommended due to lack of support](
- * For example, see the [ruby-lint gem](
+For details, see discussion [with Grant Olson]( and
+[Yorick Peterse](
Several sources were used for content for this guide:
+* [How to cryptographically sign your RubyGem]( - Step-by-step guide
* [Signing rubygems - Pasteable instructions](
* [Twitter gem gemspec](
* [RubyGems Trust Model Overview](, [doc](
Something went wrong with that request. Please try again.