README.md in r509-ocsp-responder-0.3.1 vs README.md in r509-ocsp-responder-0.3.2
- old
+ new
@@ -1,21 +1,118 @@
#r509-ocsp-responder [](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.
+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), and [dependo](https://github.com/sirsean/dependo). Optionally, you can install [r509-ocsp-stats](https://github.com/sirsean/r509-ocsp-stats) for stats collection. 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.
+###Build/Install
+If you have cloned the repo you can build the gem with ```rake gem:build``` and install with ```rake gem:install``` . Alternately you can use a prebuilt gem by typing ```gem install r509-ocsp-responder``` .
-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.
+###Set Up config.ru
+Save the below into a config.ru (or rackup) file
+```ruby
+require "r509"
+require "dependo"
+require 'r509/ocsp/responder/server'
+
+Dependo::Registry[:log] = Logger.new(STDOUT)
+
+require "r509/validity/redis"
+require 'redis'
+begin
+ gem "hiredis"
+ Dependo::Registry[:log].warn "Loading redis with hiredis driver"
+ redis = Redis.new(:driver => :hiredis)
+rescue Gem::LoadError
+ Dependo::Registry[:log].warn "Loading redis with standard ruby driver"
+ redis = Redis.new
+end
+Dependo::Registry[:validity_checker] = R509::Validity::Redis::Checker.new(redis)
+
+
+R509::OCSP::Responder::OCSPConfig.load_config
+
+R509::OCSP::Responder::OCSPConfig.print_config
+
+# Uncomment the next two lines if you want to collect stats via r509-ocsp-stats
+# require "r509/ocsp/stats/redis"
+# Dependo::Registry[:stats] = R509::OCSP::Stats::Redis.new
+
+responder = R509::OCSP::Responder::Server
+run responder
+```
+
+
+###Configure config.yaml
+The config.yaml contains certificate authority nodes as well as options like copy_nonce (documented below). Each CA node has an arbitrary name like test_ca and contains a ca_cert and (optional) ocsp_cert node. If you want to sign OCSP responses directly from your root you'll set your config up like this:
+
```yaml
+copy_nonce: true
+cache_headers: true
+max_cache_age: 60
+certificate_authorities: {
+ second_ca: {
+ ca_cert: {
+ cert: "spec/fixtures/second_ca.cer",
+ key: "spec/fixtures/second_ca.key"
+ }
+ }
+}
+```
+
+If you want to use an OCSP delegate
+
+```yaml
+copy_nonce: true
+cache_headers: true
+max_cache_age: 60
+certificate_authorities: {
+ test_ca: {
+ ca_cert: {
+ cert: "spec/fixtures/test_ca.cer"
+ },
+ ocsp_cert: {
+ cert: "spec/fixtures/test_ca_ocsp.cer",
+ key: "spec/fixtures/test_ca_ocsp.key"
+ }
+ }
+}
+```
+
+Finally, if you're responding for multiple roots you specify them like so:
+
+```yaml
+copy_nonce: true
+cache_headers: true
+max_cache_age: 60
+certificate_authorities: {
+ test_ca: {
+ ca_cert: {
+ cert: "spec/fixtures/test_ca.cer"
+ },
+ ocsp_cert: {
+ cert: "spec/fixtures/test_ca_ocsp.cer",
+ key: "spec/fixtures/test_ca_ocsp.key"
+ }
+ },
+ second_ca: {
+ ca_cert: {
+ cert: "spec/fixtures/second_ca.cer",
+ key: "spec/fixtures/second_ca.key"
+ }
+ }
+}
+```
+
+###Configure Thin & nginx
+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
@@ -28,22 +125,22 @@
```
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 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;
+ listen 80;
+ server_name ocsp.r509.org;
- location / {
- proxy_pass http://thin_ocsp_responder;
- proxy_cache ocsp;
- proxy_cache_use_stale updating;
- }
+ 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:
@@ -62,11 +159,9 @@
* __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