r509-ocsp-responder 0.3.1

data/README.md

@@ -0,0 +1,77 @@
+#r509-ocsp-responder [![Build Status](https://secure.travis-ci.org/reaperhulk/r509-ocsp-responder.png)](http://travis-ci.org/reaperhulk/r509-ocsp-responder)
+r509-ocsp-responder is an OCSP responder written using [r509](https://github.com/reaperhulk/r509) and Sinatra to conform to RFC [2560](http://www.ietf.org/rfc/rfc2560.txt) and [5019](http://www.ietf.org/rfc/rfc5019.txt).
+
+##Requirements
+
+r509-ocsp-responder depends on [r509](https://github.com/reaperhulk/r509), [redis](http://redis.io), [r509-validity-redis](https://github.com/sirsean/r509-validity-redis) (or another library that implements R509::Validity), [sinatra](http://sinatrarb.com), [r509-ocsp-stats](https://github.com/sirsean/r509-ocsp-stats), and [dependo](https://github.com/sirsean/dependo). These must be installed as gems.
+
+##Basic Usage
+
+1. Build the gem. If you have cloned the repo you can build the gem with ```rake gem:build```. You will need
+2. Install the gem. ```rake gem:install```
+3. Set up your config.ru and config.yaml. At this time you'll need to copy the config.ru from the gem install to another dir with your config.yaml. You should also copy (and modify) the config.yaml.example file from the gem. You'll need to alter the config.ru's require line from ```require './lib/r509/ocsp/responder/server'``` to ```require 'r509/ocsp/responder/server'``` if you have it installed as a gem.
+
+Once you've done that you can set up your rack server. The example below is an example yaml config for thin. You will want to have as many servers as you have cores.
+
+```yaml
+chdir: /var/www/r509-ocsp-responder
+rackup: /var/www/r509-ocsp-responder/config.ru
+socket: /var/run/r509-ocsp-responder.sock
+pid: /var/run/r509-ocsp-responder.pid
+servers: 2
+daemonize: true
+log: /var/log/r509-ocsp-responder.log
+```
+
+Since this config is just using sockets let's set up nginx as a reverse proxy for the thin instances. We can also use this as a caching layer if we choose to enable cache_headers.
+
+```
+proxy_cache_path  /var/www/cache levels=1:2 keys_zone=ocsp:8m max_size=16m inactive=64m;
+proxy_temp_path /var/www/cache/tmp;
+
+upstream thin_ocsp_responder{
+    server unix:/var/run/r509-ocsp-responder.0.sock fail_timeout=0;
+    server unix:/var/run/r509-ocsp-responder.1.sock fail_timeout=0;
+}
+server {
+    listen       80;
+    server_name  ocsp.r509.org;
+
+    location / {
+        proxy_pass http://thin_ocsp_responder;
+        proxy_cache ocsp;
+        proxy_cache_use_stale updating;
+    }
+}
+```
+
+Within the location block you may also choose to add these directives:
+
+```
+proxy_cache_methods GET POST;
+proxy_cache_valid  200 302  1m;
+```
+
+If present, these lines will cause 200 and 302 responses to POST and GET to be cached for 1 minute. This allows you to cache POST requests (Note: Per the HTTP RFC POST requests should not be cached) in addition to the GET requests normally supported by the ruby layer. __NOTE:__ The proxy\_cache\_valid values are lower priority than caching headers sent by the thin instances so if you do not keep the value here in sync with the max\_cache\_age config (or turn off cache\_headers entirely and solely control it through nginx) you will have mismatched cache times. Additionally, this will cache nonced responses, which wastes RAM since they will not be re-used.
+
+If you would like to track the cache utilization you can also modify the nginx logging to track cache hits. There are a variety of ways this can be accomplisehd, but one of the simplest is simply to alter your log_format line to add ```$upstream_cache_status```.
+
+##Options
+This OCSP responder supports several optional flags (in addition to supporting an arbitrary number of responder certificates).
+
+* __copy\_nonce__ - (true/false) Sets whether to copy the nonce from request to response (if present)
+
+* __cache\_headers__ - (true/false) Sets whether to set HTTP headers for caching GET responses. Coupled with a reverse proxy you can cache responses for a finite period and vastly speed up the response time of your server (at the cost of response freshness). Nonced requests will not be cached. The performance benefit of caching can vary drastically depending on the mix of clients connecting to the OCSP responder.
+
+* __max\_cache\_age__ - (integer) Sets the maximum age in __seconds__ a response can be cached. At this time r509-ocsp-responder does not support cache invalidation so it is recommended to set this to a low value to reduce the time you may serve stale responses in the event of a revocation.
+
+See the config.yaml.example for an example configuration.
+
+##Signals
+You can send a kill -USR2 signal to any running r509-ocsp-responder process to cause it to reload and print its config to the logs (provided your app server isn't trapping USR2 first).
+
+##Running Tests
+You'll need rspec, rake, and rack-test to run the tests. With these gems in place run ```rake spec```
+
+##Future Ideas
+* Devise a mechanism for doing automated OCSP delegate certificate renewal

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rspec/core/rake_task'
+require "#{File.dirname(__FILE__)}/lib/r509/ocsp/responder/version"
+
+task :default => :spec
+RSpec::Core::RakeTask.new(:spec) do
+    ENV['RACK_ENV'] = 'test'
+end
+
+desc 'Run all rspec tests with rcov (1.8 only)'
+RSpec::Core::RakeTask.new(:rcov) do |t|
+    t.rcov_opts =  %q[--exclude "spec,gems"]
+    t.rcov = true
+end
+
+namespace :gem do
+    desc 'Build the gem'
+    task :build do
+        puts `yard`
+        puts `gem build r509-ocsp-responder.gemspec`
+    end
+
+    desc 'Install gem'
+    task :install do
+        puts `gem install r509-ocsp-responder-#{R509::Ocsp::Responder::VERSION}.gem`
+    end
+
+    desc 'Uninstall gem'
+    task :uninstall do
+        puts `gem uninstall r509-ocsp-responder`
+    end
+end
+
+desc 'Build yard documentation'
+task :yard do
+    puts `yard`
+    `open doc/index.html`
+end

data/doc/R509.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Module: R509
+  
+    &mdash; Documentation by YARD 0.8.2.1
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '';
+  framesUrl = "frames.html#!" + escape(window.location.href);
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+  
+    <a href="_index.html">Index (R)</a> &raquo;
+    
+    
+    <span class="title">R509</span>
+  
+
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+
+      <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+      Class List
+    </a>
+  
+    <a class="full_list_link" id="method_list_link"
+        href="method_list.html">
+      Method List
+    </a>
+  
+    <a class="full_list_link" id="file_list_link"
+        href="file_list.html">
+      File List
+    </a>
+  
+</div>
+      <div class="clear"></div>
+    </div>
+
+    <iframe id="search_frame"></iframe>
+
+    <div id="content"><h1>Module: R509
+  
+  
+  
+</h1>
+
+<dl class="box">
+  
+  
+    
+  
+    
+  
+  
+  
+    <dt class="r1 last">Defined in:</dt>
+    <dd class="r1 last">lib/r509/ocsp/responder/version.rb</dd>
+  
+</dl>
+<div class="clear"></div>
+
+<h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="R509/Ocsp.html" title="R509::Ocsp (module)">Ocsp</a></span>
+    
+  
+    
+  
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+    <div id="footer">
+  Generated on Thu Nov  8 14:33:52 2012 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.2.1 (ruby-1.9.3).
+</div>
+
+  </body>
+</html>

data/doc/R509/Ocsp.html

@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Module: R509::Ocsp
+  
+    &mdash; Documentation by YARD 0.8.2.1
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" media="screen" charset="utf-8" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" media="screen" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '../';
+  framesUrl = "../frames.html#!" + escape(window.location.href);
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+  
+    <a href="../_index.html">Index (O)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../R509.html" title="R509 (module)">R509</a></span></span>
+     &raquo; 
+    <span class="title">Ocsp</span>
+  
+
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+
+      <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+      Class List
+    </a>
+  
+    <a class="full_list_link" id="method_list_link"
+        href="../method_list.html">
+      Method List
+    </a>
+  
+    <a class="full_list_link" id="file_list_link"
+        href="../file_list.html">
+      File List
+    </a>
+  
+</div>
+      <div class="clear"></div>
+    </div>
+
+    <iframe id="search_frame"></iframe>
+
+    <div id="content"><h1>Module: R509::Ocsp
+  
+  
+  
+</h1>
+
+<dl class="box">
+  
+  
+    
+  
+    
+  
+  
+  
+    <dt class="r1 last">Defined in:</dt>
+    <dd class="r1 last">lib/r509/ocsp/signer.rb<span class="defines">,<br />
+  lib/r509/ocsp/responder/version.rb</span>
+</dd>
+  
+</dl>
+<div class="clear"></div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>OCSP related classes (signing, response, request)</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Ocsp/Helper.html" title="R509::Ocsp::Helper (module)">Helper</a></span>, <span class='object_link'><a href="Ocsp/Responder.html" title="R509::Ocsp::Responder (module)">Responder</a></span>
+    
+  
+    
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Ocsp/Signer.html" title="R509::Ocsp::Signer (class)">Signer</a></span>
+    
+  
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+    <div id="footer">
+  Generated on Thu Nov  8 14:33:52 2012 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.2.1 (ruby-1.9.3).
+</div>
+
+  </body>
+</html>

data/doc/R509/Ocsp/Helper.html

@@ -0,0 +1,126 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Module: R509::Ocsp::Helper
+  
+    &mdash; Documentation by YARD 0.8.2.1
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" media="screen" charset="utf-8" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" media="screen" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '../../';
+  framesUrl = "../../frames.html#!" + escape(window.location.href);
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+  
+    <a href="../../_index.html">Index (H)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../R509.html" title="R509 (module)">R509</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Ocsp.html" title="R509::Ocsp (module)">Ocsp</a></span></span>
+     &raquo; 
+    <span class="title">Helper</span>
+  
+
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+
+      <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+      Class List
+    </a>
+  
+    <a class="full_list_link" id="method_list_link"
+        href="../../method_list.html">
+      Method List
+    </a>
+  
+    <a class="full_list_link" id="file_list_link"
+        href="../../file_list.html">
+      File List
+    </a>
+  
+</div>
+      <div class="clear"></div>
+    </div>
+
+    <iframe id="search_frame"></iframe>
+
+    <div id="content"><h1>Module: R509::Ocsp::Helper
+  
+  
+  
+</h1>
+
+<dl class="box">
+  
+  
+    
+  
+    
+  
+  
+  
+    <dt class="r1 last">Defined in:</dt>
+    <dd class="r1 last">lib/r509/ocsp/signer.rb</dd>
+  
+</dl>
+<div class="clear"></div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Helper module for OCSP handling</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+  
+    
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Helper/RequestChecker.html" title="R509::Ocsp::Helper::RequestChecker (class)">RequestChecker</a></span>, <span class='object_link'><a href="Helper/ResponseSigner.html" title="R509::Ocsp::Helper::ResponseSigner (class)">ResponseSigner</a></span>
+    
+  
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+    <div id="footer">
+  Generated on Thu Nov  8 14:33:52 2012 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.2.1 (ruby-1.9.3).
+</div>
+
+  </body>
+</html>