ssl_allow_cname 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd9a1a0a538978860ac3c85759c5b63e123353e1
-  data.tar.gz: 38374a3700d5292652387643fcc9ad404faed984
+  metadata.gz: a3b389210ba7957980da18153a64873506de72e1
+  data.tar.gz: a3e4f3f79048eb0e5908aedc24de736623b82915
 SHA512:
-  metadata.gz: cbaa6fd49e2bd2d432e021726a31601e3a31d1e4c993784370230ce228142f2ed39c99120df3e8ef6ccc1bad93b370f654b8d70e1e0d37ae23de3550b5949aa1
-  data.tar.gz: 651865332f539e2aa1db220ff46eb45d58dc7eb9326bb8f92c5e55f961505d5e2608dcd8a68e67349f2ff88a65dd16681f3010e69609a3f10061332225a267cd
+  metadata.gz: 910e208f3d9d38c2b69da7bff3f141e0aa317078756fa25411886d0180cea3bfc995594b06692ec504156f1c27dff45bcfc6c8c1d3eae4870b591bc44c640f1b
+  data.tar.gz: eb215150b1059368209e14357e3f7c141745a294262ca3c5f2bd18f94877a8150c57d5b72a77e20a7f23f7eccf4a993f3a88f513516a471afbf1fde420725c73

data/README.md

@@ -1,6 +1,53 @@
-# SslAllowCname
+# ssl_allow_cname
 
-This adds an SSL parameter: 'allow_cname', which can be a string, regexp, or
-proc, or array of any of the preceding.
+`ssl_allow_cname` adds a parameter to Ruby's OpenSSL library: `allow_cname`.
 
-This is will be further documented in the future.
+This is for cases when you don't care about the host matching the CommonName or
+a SubjectAlternateName of a certificate (e.g., you've got other security
+measures), but surely don't want to turn off all peer verification.
+
+Here's an example:
+
+```ruby
+# This actually works, using the Ruby redis client's SSL support:
+
+redis = Redis.new(
+  # Say the other side of this connection has a certificate you've signed, but
+  # you don't care what VPS instance it ends on with an arbitrary IP.
+  url: 'rediss://198.199.120.202/',  
+  ssl_params: {
+    # And you only trust yourself as a CA.
+    ca_file: '/etc/ssl/metermd/metermd-ca.crt',
+
+    # And the following cert has been signed by your CA, and the key's valid...
+    cert: OpenSSL::X509::Certificate.new(File.read('/etc/ssl/metermd/redis-client.crt')),
+    key: OpenSSL::PKey::RSA.new(File.read('/etc/ssl/metermd/redis-client.keydh')),
+
+    # You just care that you've authorized this certificate for this purpose,
+    # and rely on the security of your CA being legit.
+    allow_cname: 'redis-server'
+  }
+)
+```
+
+Using the `allow_cname` option disables host verification, but specifying
+`allow_cname: :match` will give you the same behavior as peer verification.
+When you don't specify `allow_cname`, everything works the same as out-of-the-
+box.
+
+The value passed to `allow_cname` can take a few forms:
+
+  * A `String`, which means the CommonName presented must exactly match what
+    you've specified.
+  * A `Regexp`, which will pass if it matches the CommonName of the peer
+    certificate.
+  * A `Proc`, which can accept either `(common_name)` or `(common_name, host)`
+    argument lists.  Return `true` if you like it, false otherwise.
+  * The symbol `:match`, which accepts anything OpenSSL would've considered
+    valid.
+  * An `Array` of any of the above, which **operates in an OR, not AND,
+    fashion.**
+
+For simplicity, and to make it easier to not get wrong, `ssl_allow_cname` does
+not consider SubjectAlternateNames, just the first CommonName.  If you're
+running your own CA, you'll be able to arrange this.

data/lib/ssl_allow_cname.rb

@@ -10,6 +10,11 @@ module SslAllowCname
     def post_connection_check(hostname)
       return super if context.allow_cname.nil?
 
+      if peer_cert.nil?
+        msg = "allow_cname specified, but peer presented no certificate"
+        raise OpenSSL::SSL::SSLError, msg
+      end
+
       cname = peer_cert.subject.to_a.map do |oid, value|
         oid == 'CN' ? value : nil
       end.compact.first
@@ -36,6 +41,7 @@ module SslAllowCname
                                      "predicate in :allow_cname.  Use :match " +
                                      "to get normal CommonName/Host validation"
       end
+      true
     end
   end
 end

data/lib/ssl_allow_cname/version.rb

@@ -1,3 +1,3 @@
 module SslAllowCname
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ssl_allow_cname
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Mike A. Owens
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-10 00:00:00.000000000 Z
+date: 2016-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler