certificate_authority_sonian 0.1.7

data/Gemfile

@@ -0,0 +1,9 @@
+source 'http://rubygems.org'
+
+gem 'activemodel', ">= 3.0.6"
+
+group :development do
+	gem 'rspec'
+  gem "jeweler", ">= 1.5.2"
+  #gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,39 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.2.8)
+      activesupport (= 3.2.8)
+      builder (~> 3.0.0)
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    i18n (0.6.0)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.4)
+    multi_json (1.3.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.2)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel (>= 3.0.6)
+  jeweler (>= 1.5.2)
+  rspec

data/README.rdoc

@@ -0,0 +1,243 @@
+= CertificateAuthority - Because it shouldn't be this damned complicated
+
+This is meant to provide a (more) programmer-friendly implementation of all the basic functionality contained in RFC-3280 to implement your own certificate authority.
+
+You can generate root certificates, intermediate certificates, and terminal certificates.  You can also generate/manage Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) messages.
+
+Because this library is built using the native Ruby bindings for OpenSSL it also supports PKCS#11 cryptographic hardware for secure maintenance of private key materials.
+
+= So you want to maintain a certificate authority root
+
+Let's suppose hypothetically you want to be able to issue and manage your own certificates. This section is meant to outline the basic functions you'll need(optionally want) to support.  Not everyone is out to be in total compliance with WebTrust[link:http://www.webtrust.org/] or {Mozilla's rules for CA inclusion}[link:https://wiki.mozilla.org/CA:How_to_apply].
+
+The three primary elements to be aware of are:
+
+[Certificate Authority] These are the functions primarily related to the signing, issuance, and revocation of certificates.
+
+[Registration Authority] These are the functions primarily related to registering and requesting certificates and vetting of the entities requesting certification.
+
+[Validation Authority] These are the functions related to verifying the status of certificates out in the wild.  Mostly CRLs and OCSP related functions.
+
+= Establishing a new root in software
+
+Let's look at a complete example for generating a new root certificate. Assuming that you don't have a PKCS#11 hardware token available (lists coming...) we'll have to store this safe.
+
+Generating a self-signed root certificate is fairly easy:
+
+  require 'certificate_authority'
+  root = CertificateAuthority::Certificate.new
+  root.subject.common_name= "http://mydomain.com"
+  root.serial_number.number=1
+  root.key_material.generate_key
+  root.signing_entity = true
+  signing_profile = {"extensions" => {"keyUsage" => {"usage" => ["critical", "keyCertSign"] }} }
+  root.sign!(signing_profile)
+
+The required elements for the gem at this time are a common name for the subject and a serial number for the certificate. Since this is our self-signed root we're going to give it the first serial available of 1. Because certificate_authority is not designed to manage the issuance lifecycle you'll be expected to store serial numbers yourself.
+
+Next, after taking care of required fields, we will require key material for the new certificate.  There's a convenience method made available on the key_material object for generating new keys.  The private key will be available in:
+
+  root.key_material.private_key
+
+and the public key:
+
+  root.key_material.public_key
+
+Make sure to save the private key somewhere safe!
+
+Lastly, we declare that the certificate we're about to sign is itself a signing entity so we can continue on and sign other certificates.
+
+== Creating a new intermediate
+
+Maybe you don't want to actually sign certificates with your super-secret root certificate. This is actually how a good number of most public certificate authorities do it. Rather than sign with the primary root, they generate an intermediate root that is then responsible for signing the final certificates.  If you wanted to create an intermediate root certificate you would do something like the following:
+
+  intermediate = CertificateAuthority::Certificate.new
+  intermediate.subject.common_name= "My snazzy intermediate!"
+  intermediate.serial_number.number=2
+  intermediate.key_material.generate_key
+  intermediate.signing_entity = true
+  intermediate.parent = root
+  signing_profile = {"extensions" => {"keyUsage" => {"usage" => ["critical", "keyCertSign"] }} }
+  intermediate.sign!(signing_profile)
+
+All we have to do is create another certificate like we did with the root. In this example we gave it the next available serial number which for us, was 2.  We then generate (and save!) key material for this new entity.  Even the +signing_entity+ is set to true so this certificate can sign other certificates.  The difference here is that the +parent+ field is set to the root. Going forward, whatever entity you want to sign a certificate, you set that entity to be the parent. In this case, our root will be responsible for signing this intermediate when we call +sign!+.
+
+= Creating new certificates (in general)
+
+Now that we have a root certificate (and possibly an intermediate) we can sign end-user certificates.  It is, perhaps unsurprisingly, similar to all the others:
+
+  plain_cert = CertificateAuthority::Certificate.new
+  plain_cert.subject.common_name= "http://mydomain.com"
+  plain_cert.serial_number.number=4
+  plain_cert.key_material.generate_key
+  plain_cert.parent = root # or intermediate
+  plain_cert.sign!
+
+That's all there is to it!  In this example we generate the key material ourselves, but it's possible for the end-user to generate certificate signing request (CSR) that we can then parse and consume automatically (coming soon).  To get the PEM formatted certificate for the user you would need to call:
+
+  plain_cert.to_pem
+
+to get the certificate body.
+
+= Signing Profiles
+
+Creating basic certificates is all well and good, but maybe you want _more_ signing control.  +certificate_authority+ supports the idea of signing profiles.  These are hashes containing values that +sign!+ will use to merge in additional control options for setting extensions on the certificate.
+
+Here's an example of a full signing profile for most of the common V3 extensions:
+
+   signing_profile = {
+     "extensions" => {
+       "basicConstraints" => {"ca" => false},
+       "crlDistributionPoints" => {"uri" => "http://notme.com/other.crl" },
+       "subjectKeyIdentifier" => {},
+       "authorityKeyIdentifier" => {},
+       "authorityInfoAccess" => {"ocsp" => ["http://youFillThisOut/ocsp/"] },
+       "keyUsage" => {"usage" => ["digitalSignature","nonRepudiation"] },
+       "extendedKeyUsage" => {"usage" => [ "serverAuth","clientAuth"]},
+       "subjectAltName" => {"uris" => ["http://subdomains.youFillThisOut/"]},
+       "certificatePolicies" => {
+       "policy_identifier" => "1.3.5.8", "cps_uris" => ["http://my.host.name/", "http://my.your.name/"], 
+         "user_notice" => {
+          "explicit_text" => "Explicit Text Here", 
+         "organization" => "Organization name",
+         "notice_numbers" => "1,2,3,4"
+         }
+       }
+     }
+  }
+
+Using a signing profile is done this way:
+
+  certificate.sign!(signing_profile)
+
+At that point all the configuration options will be merged into the extensions.
+
+== Basic Constraints
+
+The basic constraints extension allows you to control whether or not a certificate can sign other certificates.
+
+[CA] If this value is true then this certificate has the authority to sign additional certificates.
+
+[pathlen] This is the maximum length of the chain-of-trust.  For instance, if an intermediate certificate has a pathlen of 1 then it can sign additional certificates, but it cannot create another signing entity because the total chain-of-trust would have a length greater than 1.
+
+== CRL Distribution Points
+
+This extension controls where a conformant client can go to obtain a list of certificate revocation information.  At this point +certificate_authority+ only supports a list of URIs.  The formal RFC however provides for the ability to provide a URI and an issuer identifier that allows a different signing entity to generate/sign the CRL.
+
+[uri] The URI in subject alternative name format of the URI endpoint.  Example: "http://ca.chrischandler.name/some_identifier.crl"
+
+== Subject Key Identifier
+
+This extension is required to be present, but doesn't offer any configurable parameters.  Directly from the RFC:
+
+  The subject key identifier extension provides a means of identifying
+  certificates that contain a particular public key.
+
+  To facilitate certification path construction, this extension MUST
+  appear in all conforming CA certificates, that is, all certificates
+  including the basic constraints extension (section 4.2.1.10) where
+  the value of cA is TRUE.  The value of the subject key identifier
+  MUST be the value placed in the key identifier field of the Authority
+  Key Identifier extension (section 4.2.1.1) of certificates issued by
+  the subject of this certificate.
+
+== Authority Key Identifier
+
+Just like the subject key identifier, this is required under most circumstances and doesn't contain any meaningful configuration options.  From the RFC:
+
+  The keyIdentifier field of the authorityKeyIdentifier extension MUST
+  be included in all certificates generated by conforming CAs to
+  facilitate certification path construction.  There is one exception;
+  where a CA distributes its public key in the form of a "self-signed"
+  certificate, the authority key identifier MAY be omitted.  The
+  signature on a self-signed certificate is generated with the private
+  key associated with the certificate's subject public key.  (This
+  proves that the issuer possesses both the public and private keys.)
+  In this case, the subject and authority key identifiers would be
+  identical, but only the subject key identifier is needed for
+  certification path building.
+
+== Authority Info Access
+
+The authority info access extension allows a CA to sign a certificate with information a client can use to get up-to-the-minute status information on a signed certificate.  This takes the form of an OCSP[link:http://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol] (Online Certificate Status Protocol) endpoints.
+
+[ocsp] This is an array of URIs specifying possible endpoints that will be able to provide a signed response. +certificate_authority+ has an OCSP message handler for parsing OCSP requests and generating OCSP signed responses.
+
+== Key Usage
+
+This extension contains a list of the functions this certificate is allowed to participate in.
+
+[usage] An array of OIDs in string format. The acceptable values are specified by OpenSSL and are: +digitalSignature+, +nonRepudiation+, +keyEncipherment+, +dataEncipherment+, +keyAgreement+, +keyCertSign+, +cRLSign+, +encipherOnly+ and +decipherOnly+.
+
+== Extended Key Usage
+
+This one is like key usage, but allows for certain application specific purposes. It's generally only present in end-user certificates.
+
+[usage] An array of OIDs in string format. The only ones with practical significance at this point are: +serverAuth+, +clientAuth+, and +codeSigning+.
+
+== Subject Alternative Name
+
+If the certificate needs to work for multiple domains then you can specify the others for which it is valid in the subject alternative name field.
+
+[uris] An array of full URIs for other common names this certificate should be valid for. For instance, if you want http://ca.chrischandler.name and http://www.ca.chrischandler.name to share the same cert you would place both in the +uris+ attribute of the subject alternative name.
+
+== Certificate Policies
+
+This is one of the most esoteric of the extensions. This allows a conformant certificate authority to embed signing policy information into the certificate body. Public certificate authorities are required to maintain a Certificate Practice Statement in accordance with {RFC 2527}[link:http://www.ietf.org/rfc/rfc2527.txt].
+
+These CPSs define what vetting criteria and maintenance practices are required to issue, maintain, and revoke a certificate. While it might be overkill for private certificates, if you wanted to make an actual public CA you would need to put together a practice statement and embed it in certificates you issue.
+
+[policy_identifier] This is an arbitrary OID (that you make up!) that uniquely represents the policy you are enforcing for whatever kind of certificate this is meant to be.
+
+[cps_uris] This is an array of URIs where a client or human can go to get information related to your certification practice.
+
+[user_notice] This is a nested field containing explicit human readable text if you want to embed a notice in the certificate body related to certification practices. It contains nested attributes of +explicit_text+ for the notice, +organization+ and +notice_numbers+. Refer to the RFC for specific implications of how these are set, but whether or not browsers implement the correct specified behavior for their presence is another issue.
+
+= PKCS#11 Support
+
+If you happen to have a PKCS#11 compliant hardware token you can use +certificate_authority+ to maintain private key materials in hardware security modules. At this point the scope of operating that hardware is out of scope of this README but it's there and it is supported.
+
+To configure a certificate to utilize PKCS#11 instead of in memory keys all you need to do is:
+
+  root = CertificateAuthority::Certificate.new
+  root.subject.common_name= "http://mydomain.com"
+  root.serial_number.number=1
+  root.signing_entity = true
+
+  key_material_in_hardware = CertificateAuthority::Pkcs11KeyMaterial.new
+  key_material_in_hardware.token_id = "46"
+  key_material_in_hardware.pkcs11_lib = "/usr/lib/libeTPkcs11.so"
+  key_material_in_hardware.openssl_pkcs11_engine_lib = "/usr/lib/engines/engine_pkcs11.so"
+  key_material_in_hardware.pin = "11111111"
+
+  root.key_material = key_material_in_hardware
+  root.sign!
+
+Your current version of OpenSSL _must_ include dynamic engine support and you will need to have OpenSSL PKCS#11 engine support.  You will also require the actual PKCS#11 driver from the hardware manufacturer.  As of today the only tokens I've gotten to work are:
+
+[eTokenPro] Released by Aladdin (now SafeNet Inc.). I have only had success with the version 4 and 5 (32 bit only) copy of the driver. The newer authentication client released by SafeNet appears to be completely broken for interacting with the tokens outside of SafeNet's own tools. If anyone has a different experience I'd like to hear from you.
+
+[ACS CryptoMate] Also a 32-bit only driver. You'll have to jump through some hoops to get the Linux PKCS#11 driver but it works surprisingly well. It also appears to support symmetric key operations in hardware.
+
+[Your company] Do you make a PKCS#11 device? I'd love to get it working but I probably can't afford your device. Get in touch with me and if you're willing to loan me one for a week I can get it listed.
+
+Also of note, I have gotten these to work with 32-bit copies of Ubuntu 10.10 and pre-Snow Leopard versions of OS X. If you are running Snow Leopard you're out of luck since none of the companies I've contacted make a 64 bit driver.
+
+= Coming Soon
+
+* More PKCS#11 hardware (I need driver support from the manufacturers)
+* Support for working with CSRs to request & issue certificates
+
+= Misc notes
+
+* Firefox will complain about root/intermediate certificates unless both digitalSignature and keyEncipherment are specified as keyUsage attributes. Thanks diogomonica
+
+== Meta
+
+Written by Chris Chandler(http://chrischandler.name)
+
+Released under the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+Main page: http://github.com/cchandler/certificate_authority
+
+Issue tracking: https://github.com/cchandler/certificate_authority/issues

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'bundler'
+require 'rspec'
+require 'rspec/core/rake_task'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "certificate_authority"
+  gem.homepage = "http://github.com/cchandler/certificate_authority"
+  gem.license = "MIT"
+  gem.summary = 'Ruby gem for managing the core functions outlined in RFC-3280 for PKI'
+  # gem.description = ''
+  gem.email = "chris@flatterline.com"
+  gem.authors = ["Chris Chandler"]
+  
+  # gem.add_dependency('activemodel', '3.0.6')
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :spec do
+  Rake::Task["spec:units"].invoke
+end
+
+namespace :spec do
+  desc "Run unit specs."
+  RSpec::Core::RakeTask.new(:units) do |t|
+    t.rspec_opts = ['--colour --format progress --tag ~pkcs11']
+  end
+
+  desc "Run integration specs."
+  RSpec::Core::RakeTask.new(:integrations) do |t|
+    t.rspec_opts   = ['--colour --format progress']
+  end
+end
+
+RSpec::Core::RakeTask.new(:doc) do |t|
+  t.rspec_opts   = ['--format specdoc ']
+end

data/VERSION.yml

@@ -0,0 +1,5 @@
+---
+:major: 0
+:minor: 1
+:patch: 7
+:build: 

data/certificate_authority.gemspec

@@ -0,0 +1,71 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "certificate_authority_sonian"
+  s.version = "0.1.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["TJ Vanderpoel"]
+  s.date = "2013-01-08"
+  s.email = "tj@rubyists.com"
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION.yml",
+    "certificate_authority.gemspec",
+    "lib/certificate_authority.rb",
+    "lib/certificate_authority/certificate.rb",
+    "lib/certificate_authority/certificate_revocation_list.rb",
+    "lib/certificate_authority/distinguished_name.rb",
+    "lib/certificate_authority/extensions.rb",
+    "lib/certificate_authority/key_material.rb",
+    "lib/certificate_authority/ocsp_handler.rb",
+    "lib/certificate_authority/pkcs11_key_material.rb",
+    "lib/certificate_authority/serial_number.rb",
+    "lib/certificate_authority/signing_entity.rb",
+    "lib/tasks/certificate_authority.rake",
+    "spec/spec_helper.rb",
+    "spec/units/certificate_authority_spec.rb",
+    "spec/units/certificate_revocation_list_spec.rb",
+    "spec/units/certificate_spec.rb",
+    "spec/units/distinguished_name_spec.rb",
+    "spec/units/extensions_spec.rb",
+    "spec/units/key_material_spec.rb",
+    "spec/units/ocsp_handler_spec.rb",
+    "spec/units/pkcs11_key_material_spec.rb",
+    "spec/units/serial_number_spec.rb",
+    "spec/units/signing_entity_spec.rb",
+    "spec/units/units_helper.rb"
+  ]
+  s.homepage = "http://github.com/bougyman/certificate_authority"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.24"
+  s.summary = "Ruby gem for managing the core functions outlined in RFC-3280 for PKI"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activemodel>, [">= 3.0.6"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 1.5.2"])
+    else
+      s.add_dependency(%q<activemodel>, [">= 3.0.6"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 1.5.2"])
+    end
+  else
+    s.add_dependency(%q<activemodel>, [">= 3.0.6"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 1.5.2"])
+  end
+end

data/lib/certificate_authority.rb

@@ -0,0 +1,19 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+#Exterior requirements
+require 'openssl'
+require 'active_model'
+
+#Internal modules
+require 'certificate_authority/signing_entity'
+require 'certificate_authority/distinguished_name'
+require 'certificate_authority/serial_number'
+require 'certificate_authority/key_material'
+require 'certificate_authority/pkcs11_key_material'
+require 'certificate_authority/extensions'
+require 'certificate_authority/certificate'
+require 'certificate_authority/certificate_revocation_list'
+require 'certificate_authority/ocsp_handler'
+
+module CertificateAuthority
+end