r509-ca-http

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.

Requirements/Installation

You need r509 and sinatra. For development/tests you need rack-test and rspec.

API

GET /1/crl/:ca/get

Get the most recently generate CRL for the given :ca.

A new CRL is generated when a certificate is revoked or unrevoked, or if you explicitly generate it.

GET /1/crl/:ca/generate

Explicitly generate and get a new CRL for the given :ca.

POST /1/certificate/issue

Issue a certificate.

Required POST parameters:

  • ca
  • profile
  • validityPeriod (in days)
  • csr (or spki)
  • subject

The subject is provided like so:

subject[CN]=domain.com&subject[O]=orgname&subject[L]=locality

Optional POST parameters:

  • extensions[subjectAlternativeName]

SAN names are provided like so:

extensions[subjectAlternativeName][]=domain1.com&extensions[subjectAlternativeName][]=domain2.com

The issue method will return the PEM text of the issued certificate.

POST /1/certificate/revoke

Revoke a certificate.

Required POST parameters:

  • ca
  • serial

Optional POST parameters:

  • reason (must be an integer, if it's not provided it defaults to 0)

The revoke method returns the newly generated CRL, after revocation.

POST /1/certificate/unrevoke

Unrevoke a certificate. (IE, remove it from the CRL and return its OCSP status to valid.)

Required POST parameters:

  • ca
  • serial

The unrevoke method returns the newly generated CRL, after the certificate was removed from it.

Helper pages

These pages are present on the server, for you to work with the CA with a basic web interface. You should not expose these endpoints to anyone.

  • /test/certificate/issue

  • /test/certificate/revoke

  • /test/certificate/unrevoke

certificate_authorities (config.yaml)

You use the config.yaml 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.

Information about how to construct the YAML can be found at the official r509 documentation.

Middleware (config.ru)

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.

For that, we've created a few pieces of Rack middleware for your use.

After installing one or both of them, you'll have to edit your config.ru`` and/orconfig.yaml``` files.

Rake tasks

There are a few things you can do with Rake.

rake spec

Run all the tests.

rake gem:build

Build a gem file.

rake gem:install

Install the gem you just built.

rake gem:uninstall

Uninstall r509-ca-http.

rake yard

Generate documentation.