<!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>
File: README
— Documentation by YARD 0.8.7
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" 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</a> »
<span class="title">File: README</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"><div id='filecontents'><h1>r509-ca-http <a href="http://travis-ci.org/r509/r509-ca-http"><img src="https://secure.travis-ci.org/r509/r509-ca-http.png" alt="Build Status"></a> <a href="https://coveralls.io/r/r509/r509-ca-http"><img src="https://coveralls.io/repos/r509/r509-ca-http/badge.png" alt="Coverage Status"></a></h1>
<p>r509-ca-http is an HTTP server that runs a certificate authority, for signing SSL certificates. It supports issuance and revocation, and is intended to be part of a complete certificate authority for use in production environments.</p>
<h2>Requirements/Installation</h2>
<p>You need <a href="https://github.com/r509/r509">r509</a> and sinatra. For development/tests you need rack-test and rspec.</p>
<h2>API</h2>
<h3>GET /1/crl/:ca/get</h3>
<p>Deprecated; will be removed in a future version. Use generate instead.</p>
<h3>GET /1/crl/:ca/generate</h3>
<p>Generate and get a new CRL for the given <code>:ca</code>.</p>
<h3>POST /1/certificate/issue</h3>
<p>Issue a certificate.</p>
<p>Required POST parameters:</p>
<ul>
<li>ca</li>
<li>profile</li>
<li>validityPeriod (in seconds)</li>
<li>csr (or spki)</li>
<li>subject</li>
</ul>
<p>The subject is provided like so:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_subject'>subject</span><span class='lbracket'>[</span><span class='const'>CN</span><span class='rbracket'>]</span><span class='op'>=</span><span class='id identifier rubyid_domain'>domain</span><span class='period'>.</span><span class='id identifier rubyid_com'>com</span><span class='op'>&</span><span class='id identifier rubyid_subject'>subject</span><span class='lbracket'>[</span><span class='const'>O</span><span class='rbracket'>]</span><span class='op'>=</span><span class='id identifier rubyid_orgname'>orgname</span><span class='op'>&</span><span class='id identifier rubyid_subject'>subject</span><span class='lbracket'>[</span><span class='const'>L</span><span class='rbracket'>]</span><span class='op'>=</span><span class='id identifier rubyid_locality'>locality</span>
</code></pre>
<p>Optional POST parameters:</p>
<ul>
<li>extensions[subjectAlternativeName]</li>
<li>message_digest</li>
</ul>
<p>SAN names are provided like so:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_extensions'>extensions</span><span class='lbracket'>[</span><span class='id identifier rubyid_subjectAlternativeName'>subjectAlternativeName</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='rbracket'>]</span><span class='op'>=</span><span class='id identifier rubyid_domain1'>domain1</span><span class='period'>.</span><span class='id identifier rubyid_com'>com</span><span class='op'>&</span><span class='id identifier rubyid_extensions'>extensions</span><span class='lbracket'>[</span><span class='id identifier rubyid_subjectAlternativeName'>subjectAlternativeName</span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='rbracket'>]</span><span class='op'>=</span><span class='id identifier rubyid_domain2'>domain2</span><span class='period'>.</span><span class='id identifier rubyid_com'>com</span>
</code></pre>
<p>The issue method will return the PEM text of the issued certificate.</p>
<p>Please note that all fields subject/extension request fields encoded in a CSR are ignored in favor of the POST parameters.</p>
<h3>POST /1/certificate/revoke</h3>
<p>Revoke a certificate.</p>
<p>Required POST parameters:</p>
<ul>
<li>ca</li>
<li>serial</li>
</ul>
<p>Optional POST parameters:</p>
<ul>
<li>reason (must be an integer or nil. nil by default)</li>
</ul>
<p>The revoke method returns the newly generated CRL, after revocation.</p>
<h3>POST /1/certificate/unrevoke</h3>
<p>Unrevoke a certificate. (IE, remove it from the CRL and return its OCSP status to valid.)</p>
<p>Required POST parameters:</p>
<ul>
<li>ca</li>
<li>serial</li>
</ul>
<p>The unrevoke method returns the newly generated CRL, after the certificate was removed from it.</p>
<h2>Helper pages</h2>
<p>These pages are present on the server, for you to work with the CA with a basic web interface. You should <em>not</em> expose these endpoints to anyone.</p>
<ul>
<li><p>/test/certificate/issue</p></li>
<li><p>/test/certificate/revoke</p></li>
<li><p>/test/certificate/unrevoke</p></li>
</ul>
<h2>certificate_authorities (config.yaml)</h2>
<p>You use the <code>config.yaml</code> file to specify information about your certificate authority. You can operate multiple certificate authorities, each of which can have multiple profiles, with one instance of r509-ca-http.</p>
<p>Information about how to construct the YAML can be found at <a href="https://github.com/r509/r509">the official r509 documentation</a>.</p>
<h2>Middleware (config.ru)</h2>
<p>Running r509-ca-http will let you issue and revoke certificates. But that's not everything you need to do, if you're going to run a CA. You're going to need information about validity, and you may want to save a record of issued certificates to the filesystem.</p>
<p>For that, we've created a few pieces of Rack middleware for your use.</p>
<ul>
<li><a href="https://github.com/r509/r509-middleware-validity">r509-middleware-validity</a></li>
<li><a href="https://github.com/r509/r509-middleware-certwriter">r509-middleware-certwriter</a></li>
</ul>
<p>After installing one or both of them, you'll have to edit your <code>config.ru</code> and/or <code>config.yaml</code> files.</p>
<h2>Signals</h2>
<p>You can send a kill -USR2 signal to any running r509-ca-http process to cause it to reload and print its config to the logs (provided your app server isn't trapping USR2 first).</p>
<h2>Support</h2>
<p>You can file bugs on GitHub or join the #r509 channel on irc.freenode.net to ask questions.</p>
<h2>Rake tasks</h2>
<p>There are a few things you can do with Rake.</p>
<p><code>rake spec</code></p>
<p>Run all the tests.</p>
<p><code>rake gem:build</code></p>
<p>Build a gem file.</p>
<p><code>rake gem:install</code></p>
<p>Install the gem you just built.</p>
<p><code>rake gem:uninstall</code></p>
<p>Uninstall r509-ca-http.</p>
<p><code>rake yard</code></p>
<p>Generate documentation.</p>
</div></div>
<div id="footer">
Generated on Tue Apr 15 17:13:51 2014 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7 (ruby-2.1.1).
</div>
</body>
</html>