certificate-depot 0.3.0

data/TODO

@@ -0,0 +1,4 @@
+* Allow people to set more subject information for the CA certificate
+* Validate input
+  - Email address when creating a certificate
+  - Common name for server certificate

data/bin/depot

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+# When it's invoked directly and not from Rubygems
+if $0 == __FILE__ 
+  $:.unshift(File.expand_path('../../lib', __FILE__))
+end
+
+require 'certificate_depot'
+CertificateDepot.run(ARGV)

data/lib/certificate_depot.rb

@@ -0,0 +1,261 @@
+require 'openssl'
+require 'fileutils'
+require 'monitor'
+
+# = CertificateDepot
+#
+# The CertificateDepot manages a single depot of certificates. For more than a
+# casual understanding of these terms we need to explain a bit more about
+# certificates first. If you already know how PKI works, you can skip the
+# following paragraphs.
+#
+# == Certificate Authorities
+#
+# “[A] certificate authority or certification authority (CA) is an entity that
+# issues digital certificates for use by other parties.”
+# – http://en.wikipedia.org/wiki/Certificate_authority
+#
+# When a CA says that party A is who they say they are and you trust the CA 
+# then you can assume they are in fact party A.
+#
+# In a Public Key Infrastructure this means that the CA has a private key
+# which only he knows. He uses this key to sign certificates stating that the
+# person owning the certificate is who the certificate says they are. Because
+# there is a public key associated with the certificate anyone can use a
+# crytographic challenge to make sure the owner has the private key to this
+# certificate.
+#
+# For example: I have a certificate that says that I'm the person with the
+# email address robert@example.com. I show my certificate to Rick. Rick gets
+# my public key from the certificate and sends me a challenge. I compute the
+# right response and send it to Rick. Rick checks the response and knows I'm
+# the rightful owner of the certificate.
+#
+# A PKI infrastructure has many more uses, but we will only focus on
+# authentication in our examples.
+#
+# There are two ways in which a CA can make sure his trust network stays
+# valid. Each certificate has a limited period in which it's valid. Even if
+# the CA forgets that he has issued the certificate it will stop being valid
+# after a while. Large CA's claim this also protects against evolving
+# attack vectors against the crytography used behind the certificates. Each
+# certificate can be _revoked_ by the CA. A publicly available list of
+# revoked certificates makes it possible to check whether a certain
+# certificate is still valid according to the CA.
+#
+# == Certificate types
+#
+# Certificate authorities came up with lots of additional features. One of
+# these is a certificate type. To be more precise, there is an extension
+# to the certificate that tells in which cases you should accept the key
+# contained in the certificate. This allows the CA to limit the use of a
+# certificate to just digital signatures, encipherment, or certain types
+# of authentication.
+#
+# For simplicity Certificate Depot only knows three types; CA, Server, and
+# Client.
+#
+# == A certificate depot
+#
+# We've named the collection of all information needed to run a CA a
+# certificate depot. It holds the CA certificate and private key, all issued
+# certificates, the revokation list, and several files need to manage these.
+class CertificateDepot
+  autoload :Certificate, 'certificate_depot/certificate'
+  autoload :Keypair,     'certificate_depot/keypair'
+  autoload :Log,         'certificate_depot/log'
+  autoload :Runner,      'certificate_depot/runner'
+  autoload :Server,      'certificate_depot/server'
+  autoload :Store,       'certificate_depot/store'
+  autoload :Worker,      'certificate_depot/worker'
+  
+  # Initialize a new depot with the path to the depot directory.
+  #
+  #   depot = CertificateDepot.new('/var/lib/certificate-depot/example')
+  def initialize(path)
+    @config = OpenSSL::Config.load(self.class.openssl_config_path(path))
+  end
+  
+  # Returns the label with a descriptive name for the depot. This is usually
+  # the common name of the CA.
+  def label
+    @config['ca']['label']
+  end
+  
+  # Path to the depot directory.
+  def path
+    @config[label]['path']
+  end
+  
+  # Returns an instance of CertificateDepot::Certificate containing the
+  # certificate of the certificate authority.
+  def ca_certificate
+    @ca_certificate ||= CertificateDepot::Certificate.from_file(self.class.certificate_path(path))
+  end
+  
+  # Returns an instance of OpenSSL::PKey::RSA containing the private key
+  # of the certificate authority.
+  def ca_private_key
+    @ca_private_key ||= OpenSSL::PKey::RSA.new(File.read(self.class.key_path(path)))
+  end
+  
+  # Generates a new RSA keypair and certificate.
+  #
+  # === Defaults
+  #
+  # By default the certificate issuer is the CA of the depot and it's also
+  # signed by the CA. The serial number is the next available serial number
+  # in the depot.
+  #
+  # See CertificateDepot::Certificate#generate for all available options.
+  def generate_keypair_and_certificate(options={})
+    keypair     = CertificateDepot::Keypair.generate
+    certificate = nil
+    
+    certificates.synchronize do
+      attributes = options
+      attributes[:ca_certificate] = ca_certificate
+      attributes[:public_key]     = keypair.public_key
+      attributes[:private_key]    = ca_private_key
+      attributes[:serial_number]  = certificates.next_serial_number
+      certificate = CertificateDepot::Certificate.generate(attributes)
+      
+      certificates << certificate
+      certificates.sync
+    end
+    
+    [keypair, certificate]
+  end
+  
+  # Returns an instance of CertificateDepot::Store representing all
+  # certificates in the depot.
+  def certificates
+    if @certificates.nil?
+      @certificates = CertificateDepot::Store.new(self.class.certificates_path(path))
+      @certificates.extend(MonitorMixin)
+    end; @certificates
+  end
+  
+  def self.create_directories(path)
+    FileUtils.mkdir_p(certificates_path(path))
+    FileUtils.mkdir_p(private_path(path))
+    FileUtils.chmod(0700, private_path(path))
+    FileUtils.chmod(0755, path)
+  end
+  
+  # Writes a configuration file to disk containing the path to the depot
+  # and its name.
+  def self.create_configuration(path, label)
+    File.open(openssl_config_path(path), 'w') do |file|
+      file.write("[ ca ]
+label           = #{label}
+
+[ #{label} ]
+path            = #{path}
+")
+    end
+  end
+  
+  # Creates a CA certificate and keypair and writes it to disk.
+  def self.create_ca_certificate(path, label)
+    keypair = CertificateDepot::Keypair.generate
+    keypair.write_to(key_path(path))
+    
+    attributes = {}
+    attributes[:type]         = :ca
+    attributes[:public_key]   = keypair.public_key
+    attributes[:private_key]  = keypair.private_key
+    attributes[:organization] = label
+    certificate = CertificateDepot::Certificate.generate(attributes)
+    certificate.write_to(certificate_path(path))
+  end
+  
+  # Creates a new depot on disk.
+  #
+  #   depot = CertificateDepot.create('/var/lib/certificate-depot/example')
+  def self.create(path, label, options={})
+    attributes = options
+    create_directories(path)
+    create_configuration(path, label)
+    create_ca_certificate(path, label)
+    new(path)
+  end
+  
+  # Generates a new RSA keypair and certificate. See
+  # CertificateDepot#generate_keypair_and_certificate and
+  # CertificateDepot::Certificate.new for more information and possible
+  # options.
+  #
+  #   keypair, certificate = 
+  #     CertificateDepot.generate_keypair_and_certificate(
+  #       '/var/lib/certificate-depot/example', {
+  #         :type => :client,
+  #         :common_name => 'Robert Verkey',
+  #         :email_address => 'robert@example.com'
+  #       }
+  #     )
+  def self.generate_keypair_and_certificate(path, options={})
+    depot = new(path)
+    depot.generate_keypair_and_certificate(options)
+  end
+  
+  # Returns a string with an Apache configuration example for using TLS
+  # client certificate authentication.
+  def self.configuration_example(path)
+    "SSLEngine on
+SSLOptions +StdEnvVars
+SSLCertificateFile      \"/etc/apache/ssl/certificates/example.com.pem\"
+SSLVerifyClient require
+SSLCACertificateFile    \"#{certificate_path(path)}\""
+  end
+  
+  # Starts a server. For available options see CertificateDepot::Server.new.
+  def self.start(path, options={})
+    CertificateDepot::Server.start(new(path), options)
+  end
+  
+  # Stops a running server. Using the options you can specify where to look
+  # for the pid file. See CertificateDepot::Server.new for more information
+  # about the options.
+  def self.stop(options={})
+    CertificateDepot::Server.stop(options)
+  end
+  
+  # Runs a command to the depot. Used by the command line tool to run
+  # commands.
+  def self.run(argv)
+    runner = ::CertificateDepot::Runner.new(argv)
+    runner.run
+    runner
+  end
+  
+  # Returns the path to the configuration file given the depot path.
+  def self.openssl_config_path(path)
+    File.join(path, 'depot.cnf')
+  end
+  
+  # Returns the path to the directory with private data given the depot path.
+  def self.private_path(path)
+    File.join(path, 'private')
+  end
+  
+  # Returns the path to the generated certificates given the depot path.
+  def self.certificates_path(path)
+    File.join(path, 'certificates')
+  end
+  
+  # Returns the path to the certificate revokation list given the depot path.
+  def self.crl_path(path)
+    File.join(path, 'crl.pem')
+  end
+  
+  # Returns the path to the CA's private key given the depot path.
+  def self.key_path(path)
+    File.join(private_path(path), 'ca.key')
+  end
+  
+  # Returns the path to the CA's certificate given the depot path.
+  def self.certificate_path(path)
+    File.join(certificates_path(path), 'ca.crt')
+  end
+end

data/lib/certificate_depot/certificate.rb

@@ -0,0 +1,239 @@
+class CertificateDepot
+  # Represents an OpenSSL certificate. TLS/SSL certificates are a rather
+  # complicated mix of several standards. If you're not familiar with TLS
+  # certificates, it might help to start by reading the Wikipedia article on
+  # the subject: http://en.wikipedia.org/wiki/Public_key_certificate.
+  #
+  #   certificate = CertificateDepot::Certificate.from_file('server.pem')
+  #   certificate.issuer
+  class Certificate
+    # Our generated certificates are valid for 10 years by default.
+    DEFAULT_VALIDITY_PERIOD = 3600 * 24 * 365 * 10
+    # We create version 3 certificates. Count starts a 0 so 2 is actually 3.
+    X509v3 = 2
+    
+    # Used to map programmer readable attributes to X509 subject attributes.
+    ATTRIBUTE_MAP = {
+      :common_name              => 'CN',
+      :locality_name            => 'L',
+      :state_or_province_name   => 'ST',
+      :organization             => 'O',
+      :organizational_unit_name => 'OU',
+      :country_name             => 'C',
+      :street_address           => 'STREET',
+      :domain_component         => 'DC',
+      :user_id                  => 'UID',
+      :email_address            => 'emailAddress'
+    }
+    
+    attr_accessor :certificate
+    
+    # Creates a new certificate instance. The certificate argument should be
+    # a OpenSSL::X509::Certificate instance.
+    def initialize(certificate=nil)
+      @certificate = certificate
+    end
+    
+    # Generates a new certificate. Possible and compulsory attributes depend
+    # on the type of certificate.
+    #
+    # === Client certificate
+    #
+    # Client certificates are used to authenticate a client to a server. They
+    # are generated by setting the <tt>:type</tt> attribute to
+    # <tt>:client</tt>.
+    #
+    # ==== Compulsory
+    #
+    # * <tt>:ca_certificate</tt> - A CertificateDepot::Certificate instance
+    #   representing the Certification Authority.
+    # * <tt>:serial_number</tt> - The serial number to store in the
+    #   certificate. This number should be unique for certificates issued
+    #   by the CA.
+    # * <tt>:public_key</tt> - A public key which is the sister key of the
+    #   private key used by the client.
+    #
+    # ==== Options
+    #
+    # You can choose to either supply an instance of OpenSSL::X509::Name as
+    # the <tt>:subject</tt> attribute or supply any of the attributes listed
+    # in ATTRIBUTE_MAP to generate the subject name. For example:
+    #
+    #   generate(:common_name => 'John Doe', :email_address => 'john@example.com')
+    #
+    # === Server certificate
+    #
+    # Server certificates are used to authenticate a server to a client and
+    # set up a secure socket. They are generated by setting the <tt>:type</tt>
+    # attribute to <tt>:server</tt>.
+    #
+    # ==== Compulsory
+    #
+    # * <tt>:ca_certificate</tt> - A CertificateDepot::Certificate instance
+    #   representing the Certification Authority.
+    # * <tt>:serial_number</tt> - The serial number to store in the
+    #   certificate. This number should be unique for certificates issued
+    #   by the CA.
+    # * <tt>:public_key</tt> - A public key which is the sister key of the
+    #   private key used by the client.
+    # * <tt>:common_name</tt> - The common name has to match the hostname used
+    #   for the server. It has to be either a complete match or a wildcard
+    #   match. So <tt>*.example.com</tt> will match <tt>www.example.com</tt>
+    #   and <tt>mail.example.com</tt> but <tt>example.com</tt> will only match
+    #   <tt>example.com</tt>.
+    #
+    # ==== Options
+    #
+    # If you want to supply an instance of OpenSSL::X509::Name as the
+    # <tt>:subject</tt> of the certificate, please make sure you set the CN
+    # attribute to the correct value of the certificate will be worthless.
+    #
+    # You can choose to set any of the other X509 attributes as found in the
+    # ATTRIBUTE_MAP, but none of the are strictly necessary.
+    #
+    # === Certification Authority certificate
+    #
+    # CA certificates are used to sign all certificates issued by the CA. They
+    # are generated by setting the <tt>:type</tt> to <tt>:ca</tt>.
+    #
+    # ==== Options
+    #
+    # You can choose to either supply an instance of OpenSSL::X509::Name as
+    # the <tt>:subject</tt> attribute or supply any of the attributes listed
+    # in ATTRIBUTE_MAP to generate the subject name. For example:
+    #
+    #   subject = OpenSSL::X509::Name.new
+    #   subject.add_entry('CN', 'Certificate Depot CA')
+    #   generate(:subject => subject)
+    #
+    #   generate(:common_name => 'Certificate Depot CA')
+    #
+    # Note that this name will be used for both the subject and issuer
+    # field in the certificate because it's a so-called
+    # sign-signed certificate.
+    def generate(attributes={})
+      from         = Time.now
+      to           = Time.now + DEFAULT_VALIDITY_PERIOD
+      
+      name         =  attributes[:subject] || OpenSSL::X509::Name.new
+      ATTRIBUTE_MAP.each do |internal, x509_attribute|
+        name.add_entry(x509_attribute, attributes[internal]) if attributes[internal]
+      end
+      
+      case attributes[:type]
+      when :client, :server
+        issuer = attributes[:ca_certificate].subject
+        serial = attributes[:serial_number]
+      when :ca
+        issuer = name
+        serial = 0
+      else
+        raise ArgumentError, "Unknown certificate type #{attributes[:type]}, please specify either :client, :server, or :ca"
+      end
+      
+      raise ArgumentError, "Please supply a serial number for the certificate to generate" unless serial
+      
+      @certificate = OpenSSL::X509::Certificate.new
+      @certificate.subject    = name
+      @certificate.issuer     = issuer
+      @certificate.not_before = from
+      @certificate.not_after  = to
+      @certificate.version    = X509v3
+      @certificate.public_key = attributes[:public_key]
+      @certificate.serial     = serial
+      
+      extensions = []
+      factory = OpenSSL::X509::ExtensionFactory.new
+      factory.subject_certificate = @certificate
+      
+      case attributes[:type]
+      when :server
+        factory.issuer_certificate = attributes[:ca_certificate].certificate
+        extensions << factory.create_extension('basicConstraints', 'CA:FALSE', true)
+        extensions << factory.create_extension('keyUsage', 'digitalSignature,keyEncipherment')
+        extensions << factory.create_extension('extendedKeyUsage', 'serverAuth,clientAuth,emailProtection')
+      when :client
+        factory.issuer_certificate = attributes[:ca_certificate].certificate
+        extensions << factory.create_extension('basicConstraints', 'CA:FALSE', true)
+        extensions << factory.create_extension('keyUsage', 'nonRepudiation,digitalSignature,keyEncipherment')
+        extensions << factory.create_extension('extendedKeyUsage', 'clientAuth')
+      when :ca
+        factory.issuer_certificate = @certificate
+        extensions << factory.create_extension('basicConstraints', 'CA:TRUE', true)
+        extensions << factory.create_extension('keyUsage', 'cRLSign,keyCertSign')
+      end
+      extensions << factory.create_extension('subjectKeyIdentifier', 'hash')
+      extensions << factory.create_extension('authorityKeyIdentifier', 'keyid,issuer:always')
+      
+      @certificate.extensions = extensions
+      
+      if attributes[:private_key]
+        @certificate.sign(attributes[:private_key], OpenSSL::Digest::SHA1.new)
+      end
+      
+      @certificate
+    end
+    
+    # Writes the certificate to file. The path should be a filename pointing to
+    # an existing directory. Note that this will overwrite files without
+    # asking.
+    def write_to(path)
+      File.open(path, 'w') { |file| file.write(@certificate.to_pem) }
+    end
+    
+    # Returns the public key in the certificate.
+    def public_key
+      @certificate.public_key
+    end
+    
+    # Returns the issuer for the certificate.
+    def issuer
+      @certificate.issuer
+    end
+    
+    # Returns the subject of the certificate.
+    def subject
+      @certificate.subject
+    end
+    
+    # Returns the serial number of the certificate.
+    def serial_number
+      @certificate.serial
+    end
+    
+    # Used to support easy querying of subject attributes. See ATTRIBUTE_MAP
+    # for a complete list of supported attributes.
+    #
+    #   certificate.common_name #=> '*.example.com'
+    def method_missing(method, *attributes, &block)
+      if x509_attribute = ATTRIBUTE_MAP[method.to_sym]
+        self[x509_attribute]
+      else
+        super
+      end
+    end
+    
+    # Used to support easy querying of subject attributes. See ATTRIBUTE_MAP
+    # for a complete list of supported attributes.
+    #
+    #   certificate['common_name'] #=> '*.example.com'
+    def [](key)
+      @certificate.subject.to_a.each do |name, value, type|
+        return value if name == key
+      end; nil
+    end
+    
+    # Shortcut for CertificateDepot::Certificate#generate. See this method for
+    # more details.
+    def self.generate(attributes={})
+      certificate = new
+      certificate.generate(attributes)
+      certificate
+    end
+    
+    # Instantiates a new instance using certificate data read from file.
+    def self.from_file(path)
+      new(OpenSSL::X509::Certificate.new(File.read(path)))
+    end
+  end
+end

data/lib/certificate_depot/keypair.rb

@@ -0,0 +1,43 @@
+class CertificateDepot
+  # Represents an OpenSSL RSA key. Because RSA is part of a PKI the private
+  # key is usually paired with the public key.
+  class Keypair
+    DEFAULT_LENGTH = 2048
+    
+    attr_accessor :private_key
+    
+    # Instantiate a new Keypair with a private key. The private key should be
+    # an instance of OpenSSL::PKey::RSA.
+    def initialize(private_key=nil)
+      @private_key = private_key
+    end
+    
+    # Generates a new private and public keypair.
+    def generate
+      @private_key = OpenSSL::PKey::RSA.generate(DEFAULT_LENGTH)
+    end
+    
+    # Returns the public key
+    def public_key
+      @private_key.public_key
+    end
+    
+    # Writes the keypair to file. The path should be a filename pointing to
+    # an existing directory. Note that this will overwrite files without
+    # asking.
+    def write_to(path)
+      File.open(path, 'w') { |file| file.write(@private_key.to_pem) }
+      File.chmod(0400, path)
+    end
+    
+    # Shortcut method to generate a new keypair.
+    #
+    #   keypair = CertificateDepot::Keypair.generate
+    #   keypair.write_to('/var/lib/depot/storage/my-key.key')
+    def self.generate
+      keypair = new
+      keypair.generate
+      keypair
+    end
+  end
+end

data/lib/certificate_depot/log.rb

@@ -0,0 +1,61 @@
+class CertificateDepot
+  # Simple thead-safe logger implementation.
+  #
+  #  log = Log.new('/var/log/depot.log', :level => Log::INFO)
+  #  log.fatal('I am completely operational, and all my circuits are functioning perfectly.')
+  #  log.close
+  class Log
+    DEBUG   = 0
+    INFO    = 1
+    WARN    = 2
+    ERROR   = 3
+    FATAL   = 4
+    UNKNOWN = 5
+    # Used to stop logging altogether
+    SILENT  = 9 
+    
+    # Holds the current log file
+    attr_accessor :file
+    # Holds the current log level
+    attr_accessor :level
+    
+    # Creates a new Log instance.
+    def initialize(file, options={})
+      @file  = file
+      @level = options[:level] || DEBUG
+    end
+    
+    # Log if the error level is debug or lower.
+    def debug(*args); log(DEBUG, *args); end
+    # Log if the error level is info or lower.
+    def info(*args); log(INFO, *args); end
+    # Log if the error level is warn or lower.
+    def warn(*args); log(WARN, *args); end
+    # Log if the error level is error or lower.
+    def error(*args); log(ERROR, *args); end
+    # Log if the error level is fatal or lower.
+    def fatal(*args); log(FATAL, *args); end
+    # Log if the error level is unknown or lower.
+    def unknown(*args); log(UNKNOWN, *args); end
+    
+    # Writes a message to the log is the current loglevel is equal or greater than the message_level.
+    #
+    #   log.log(Log::DEBUG, "This is a debug message")
+    def log(message_level, *args)
+      @file.flock(File::LOCK_EX)
+      @file.write(self.class.format(*args)) if message_level >= level
+      @file.flock(File::LOCK_UN)
+    rescue IOError
+    end
+    
+    # Close the logger
+    def close
+      @file.close
+    end
+    
+    # Format the log message
+    def self.format(*args)
+      ["[#{Process.pid.to_s.rjust(5)}] ", Time.now.strftime("%Y-%m-%d %H:%M:%S"), '| ', args.first, "\n"].join
+    end
+  end
+end

data/lib/certificate_depot/runner.rb

@@ -0,0 +1,138 @@
+require 'optparse'
+ 
+class CertificateDepot
+  # The Runner class handles commands issued to the command-line utility.
+  class Runner
+    def initialize(argv)
+      @argv = argv
+      @options = {}
+    end
+    
+    # Returns an option parser.
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        #               ---------------------------------------------------------------------------
+        opts.banner =  "Usage: depot [command] [options]"
+        opts.separator ""
+        opts.separator "Commands:"
+        opts.separator "    init <path> [name]        Create a new depot on disk. You probably want"
+        opts.separator "                              to run init as root to make sure your keys"
+        opts.separator "                              will be safe."
+        opts.separator ""
+        opts.separator "    generate <path>           Create a new certificate. Writes a pem"
+        opts.separator "                              with a private key and a certificate to"
+        opts.separator "                              standard output"
+        opts.separator "                    --type    Create a client or server certificate"
+        opts.separator ""
+        opts.separator "    config <path>             Shows a configuration example for Apache for"
+        opts.separator "                              the depot."
+        opts.separator ""
+        opts.separator "    start <path>              Start a server."
+        opts.separator ""
+        opts.separator "    stop                      Stop a running server."
+        opts.separator ""
+        opts.separator "Options:"
+        opts.on("-c", "--cn [COMMON_NAME]", "Set the common name to use in the generated certificate") do |common_name|
+          @options[:common_name] = common_name
+        end
+        opts.on("-e", "--email [EMAIL]", "Set the email to use in the generated certificate") do |email|
+          @options[:email_address] = email
+        end
+        opts.on( "-u", "--uid [USERID]", "Set the user id to use in the generated certificate" ) do |user_id|
+          @options[:user_id] = user_id
+        end
+        opts.on("-t", "--type [TYPE]", "Generate a certificate of a certain type (server|client)") do |type|
+          @options[:type] = type.intern
+        end
+        opts.on("-H", "--host [HOST]", "IP address or hostname to listen on (127.0.0.1)") do |host|
+          @options[:host] = host
+        end
+        opts.on("-P", "--port [PORT]", "The port to listen on (35553)") do |port|
+          @options[:port] = port.to_i
+        end
+        opts.on("-n", "--process-count [COUNT]", "The number of worker processes to spawn (2)") do |process_count|
+          @options[:process_count] = process_count.to_i
+        end
+        opts.on("-q", "--max-connection-queue [MAX]", "The number of requests to queue on the server (10)") do |max_connection_queue|
+          @options[:max_connection_queue] = max_connection_queue.to_i
+        end
+        opts.on("-p", "--pid-file [PID_FILE]", "The file to store the server PID in (/var/run/depot.pid)") do |pid_file|
+          @options[:pid_file] = pid_file
+        end
+        opts.on("-l", "--log-file [LOG_FILE]", "The file to store the server log in (/var/log/depot.log)") do |log_file|
+          @options[:log_file] = log_file
+        end
+        opts.on("-h", "--help", "Show help") do
+          puts opts
+          exit
+        end
+      end
+    end
+    
+    # Utility method which returns false if there is a path in argv. When
+    # there is no path in argv it returns true and prins a warning.
+    def no_path(argv)
+      if argv.length == 0
+        puts "[!] Please specify the path to the depot you want to operate on"
+        true
+      else
+        false
+      end
+    end
+    
+    # Runs command with arguments. Commands and arguments are documented in
+    # the help message of the command-line utility.
+    def run_command(command, argv)
+      path = File.expand_path(argv[0].to_s)
+      case command
+      when :init
+        return if no_path(argv)
+        if argv[1]
+          label = argv[1..-1].join(' ')
+        else
+          label = path.split('/').last
+        end
+        CertificateDepot.create(path, label, @options)
+      when :generate
+        return if no_path(argv)
+        unless [:server, :client].include?(@options[:type])
+          puts "[!] Unknown certificate type `#{@options[:type]}', please specify either server or client with the --type option"
+        else
+          keypair, certificate = CertificateDepot.generate_keypair_and_certificate(path, @options)
+          puts keypair.private_key.to_s
+          puts certificate.certificate.to_s
+        end
+      when :config
+        return if no_path(argv)
+        puts CertificateDepot.configuration_example(path)
+      when :start
+        return if no_path(argv)
+        if CertificateDepot.start(path, @options)
+          puts "[!] Starting server"
+        else
+          puts "[!] Can't start the server"
+        end
+      when :stop
+        if CertificateDepot.stop(@options)
+          puts "[!] Stopping server"
+        else
+          puts "[!] Can't find a running server"
+        end
+      else
+        puts parser.to_s
+      end
+    end
+    
+    # Runs the command found in the arguments. If the arguments don't contain
+    # a command the help message is show.
+    def run
+      argv = @argv.dup
+      parser.parse!(argv)
+      if command = argv.shift
+        run_command(command.to_sym, argv)
+      else
+        puts parser.to_s
+      end
+    end
+  end
+end

data/lib/certificate_depot/server.rb

@@ -0,0 +1,287 @@
+require 'socket'
+require 'logger'
+
+class CertificateDepot
+  # The CertificateDepot server is a pre-forking server. This basically means
+  # that it forks a pre-configured number of workers.
+  #
+  #   Server
+  #    |_ worker
+  #    |_ worker
+  #    |_ ...
+  #
+  # Workers hang around until something connects to the socket. The first
+  # worker to accept the request serves it. When workers die the server starts
+  # spawning new processes until it matches the configured process count.
+  # Workers are identified by their process ID or PID.
+  #
+  # The server creates a pipe between itself and each of the workers. We call
+  # these pipes lifelines. When a worker goes down the lifeline is severed.
+  # This is used as a signal by the server to spawn new workers. If the server
+  # goes down the workers use the same trick to notice this.
+  class Server
+    attr_accessor :socket, :depot
+    
+    POSSIBLE_PID_FILES = ['/var/run/depot.pid', File.expand_path('~/.depot.pid')]
+    POSSIBLE_LOG_FILES = ['/var/log/depot.log', File.expand_path('~/depot.log')]
+    READ_BUFFER_SIZE = 16 * 1024
+    DEFAULTS = {
+      :host                 => '127.0.0.1',
+      :port                 => 35553,
+      :process_count        => 2,
+      :max_connection_queue => 10
+    }
+    
+    # Create a new server instance. The first argument is a CertificateDepot
+    # instance. The second argument contains overrides to the DEFAULTS.
+    def initialize(depot, options={})
+      @depot = depot
+      
+      # Override the default with user supplied options.
+      @options = options.dup
+      DEFAULTS.keys.each do |key|
+        @options[key] ||= DEFAULTS[key]
+      end
+      
+      # If someone specifies a PID file we have to try that instead of the
+      # default.
+      if pid_file = @options.delete(:pid_file)
+        @options[:possible_pid_files] = [pid_file]
+      else
+        @options[:possible_pid_files] = POSSIBLE_PID_FILES
+      end
+      
+      # If someone specifies a log file we have to try that instead of the
+      # default.
+      if log_file = @options.delete(:log_file)
+        @options[:possible_log_files] = [log_file]
+      else
+        @options[:possible_log_files] = POSSIBLE_LOG_FILES
+      end
+      
+      # Contains the lifelines to all the workers. They are indexed by the
+      # worker's PID.
+      @lifelines = {}
+      
+      # Workers are instances of CertificateDepot::Worker. They are indexed by
+      # their own PID.
+      @workers = {}
+      
+      # Signals received by the process
+      @signals = []
+    end
+    
+    # Returns a Log object for the server
+    def log
+      if @log.nil?
+        @options[:possible_log_files].each do |log_file|
+          begin
+            file = File.open(log_file, File::WRONLY|File::APPEND|File::CREAT)
+            @log = CertificateDepot::Log.new(file)
+          rescue Errno::EACCES
+          end
+        end
+      end; @log
+    end
+    
+    # Start behaving like a server. This method returns once the server has
+    # completely started.
+    #
+    # Forks a process and starts a runloop in the fork. The runloop does
+    # worker housekeeping. It does so in three phases. First it removes all
+    # non-functional workers from its internal structures. After that it
+    # spawns new workers if it needs to. Finally it sleeps for a while so the
+    # the runloop doesn't keep busy all the time.
+    def run
+      log.info("Starting Certificate Depot server")
+      trap_signals
+      setup_socket
+      save_pid_to_file(fork do
+        # Generate a new process group so we're no longer a child process
+        # of the TTY.
+        Process.setsid
+        reroute_stdio
+        loop do
+          break if signals_want_shutdown?
+          reap_workers
+          spawn_workers
+          sleep
+        end
+        cleanup
+      end)
+    end
+    
+    # Installs signal traps to listen for incoming signals to the process.
+    def trap_signals
+      trap(:QUIT) { @signals << :QUIT }
+      trap(:EXIT) { @signals << :EXIT }
+    end
+    
+    # Returns true when the signals received by the process demand a shutdown
+    def signals_want_shutdown?
+      !@signals.empty?
+    end
+    
+    # Make all output of interpreter go to the logfile
+    def reroute_stdio
+      $stdout = log.file
+      $stderr = log.file
+    end
+    
+    # Write the PID of the process with the mainloop to the filesystem so we
+    # read it later on to signal the server to shutdown.
+    def save_pid_to_file(pid)
+      @options[:possible_pid_files].each do |pid_file|
+        begin
+          File.open(pid_file, 'w') { |file| file.write(pid.to_s) }
+          log.debug("Writing PID to `#{pid_file}'")
+          return pid_file
+        rescue Errno::EACCES
+        end
+      end
+    end
+    
+    # Reads the PID of the process with the mainloop from the filesystem. Used
+    # for sending signals to a running server.
+    def load_pid_from_file
+      best_match = @options[:possible_pid_files].inject([]) do |matches, pid_file|
+        begin
+          log.debug("Considering reading PID from `#{pid_file}'")
+          possibility = [File.atime(pid_file), File.read(pid_file).to_i]
+          log.debug(" - created #{possibility[0]}, contains PID: #{possibility[1]}")
+          matches << possibility
+        rescue Errno::EACCES, Errno::ENOENT
+        end; matches
+      end.compact.sort.last
+      best_match[1] if best_match
+    end
+    
+    # Removes all possible PID files.
+    def remove_pid_file
+      @options[:possible_pid_files].each do |pid_file|
+        begin
+          File.unlink(pid_file)
+          log.debug("Removed PID file `#{pid_file}'")
+        rescue Errno::EACCES, Errno::ENOENT
+        end
+      end
+    end
+    
+    # Figures out if any workers died and deletes them from internal
+    # structures if they did.
+    def reap_workers
+      # Don't try to find more dead workers than the process count
+      @workers.length.times do
+        # We use +waitpid+ to find any child process which has exited. It
+        # immediately returns when there aren't any dead processes.
+        if pid = Process.waitpid(-1, Process::WNOHANG)
+          despawn_worker(pid)
+        else
+          return # Stop when we don't find any
+        end
+      end
+    end
+    
+    # Deletes references to workers from the server instance
+    def despawn_worker(pid)
+      log.debug("Removing worker #{pid}")
+      @workers.delete(pid)
+      @lifelines.delete(pid)
+    end
+    
+    # Figures out how many workers are currently running and creates new ones
+    # if needed.
+    def spawn_workers
+      missing_workers.times do
+        worker = CertificateDepot::Worker.new(self)
+        
+        lifeline = IO.pipe
+        
+        pid = fork do
+          # We close the server side of the pipe in this process otherwise we
+          # don't get a EOF when reading from it.
+          lifeline.first.close
+          worker.lifeline = lifeline.last
+          worker.run
+        end
+        
+        @workers[pid]   = worker
+        @lifelines[pid] = lifeline.first
+        
+        # We close the client side of the pipe in this process otherwise we
+        # don't get an EOF when reading from it.
+        lifeline.last.close
+        
+        log.debug("Spawned worker #{pid}")
+      end
+    end
+    
+    # Sleeps until someone wants the server main loop to wake up or when 2
+    # seconds go by. Workers can wake the server in two ways, either by
+    # writing anything to their lifeline or by severing the lifeline. The
+    # lifeline is severed when the worker dies.
+    def sleep
+      # Returns with active IO objects if any of them are written to.
+      # Otherwise it times out after two seconds.
+      if needy = IO.select(@lifelines.values, nil, @lifelines.values, 2)
+        log.debug("Detected activity on: #{needy.inspect}") 
+        # Read everything coming in on the lifelines and discard it because
+        # the contents doesn't matter.
+        needy.flatten.each do |lifeline|
+          loop { lifeline.read_nonblock(READ_BUFFER_SIZE) } unless lifeline.closed?
+        end if needy
+      end
+    rescue EOFError, Errno::EAGAIN, Errno::EINTR, Errno::EBADF, IOError
+    end
+    
+    # Cleanup all server resources.
+    def cleanup
+      log.info("Shutting down")
+      @lifelines.each do |pid, lifeline|
+        begin
+          lifeline.close
+        rescue IOError
+        end
+      end
+      socket.close
+      remove_pid_file
+    end
+    
+    # Creates the socket the server listens on and binds it to the configured
+    # host and port.
+    def setup_socket
+      self.socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM, 0)
+      address = Socket.pack_sockaddr_in(@options[:port], @options[:host])
+      socket.bind(address)
+      socket.listen(@options[:max_connection_queue])
+      log.info("Listening on #{@options[:host]}:#{@options[:port]}")
+    end
+    
+    # Returns the number of workers that need to be created in order to get to
+    # the configured process count.
+    def missing_workers
+      @options[:process_count] - @workers.length
+    end
+    
+    # Sends the QUIT signal to the server process.
+    def kill
+      Process.kill(:QUIT, load_pid_from_file)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+    
+    # Creates a new server instance and starts listening on its configured
+    # host and port. Returns once the server was started.
+    def self.start(depot, options={})
+      server = new(depot, options)
+      server.run
+    end
+    
+    # Finds the server PID and kills it causing the workers to go down as well.
+    def self.stop(options={})
+      server = new(nil, options)
+      server.kill
+    end
+  end
+end

data/lib/certificate_depot/store.rb

@@ -0,0 +1,55 @@
+class CertificateDepot
+  # Manages a directory with certificates. It's mainly used by the depot to
+  # generate a unique serial for its certificates.
+  class Store
+    attr_accessor :path
+    
+    # Creates a new Store instance. The path should be a directory containing
+    # certificates in PEM format.
+    def initialize(path)
+      @path         = path
+      @certificates = []
+      load
+    end
+    
+    # Returns the number of certificates in the store.
+    def size
+      @certificates.size
+    end
+    
+    # Returns an unused serial which can be used to generate a new certificate
+    # for the store.
+    def next_serial_number
+      size + 1
+    end
+    
+    # Append a certificate to the store.
+    def <<(certificate)
+      @certificates << certificate
+    end
+    
+    # Writes all unsaved certificates to disk.
+    def sync
+      @certificates.each do |certificate|
+        certificate_path = File.join(@path, "#{certificate.serial_number}.crt")
+        unless File.exist?(certificate_path)
+          certificate.write_to(certificate_path)
+        end
+      end
+    end
+    
+    # Reads all certificates from disk.
+    def load
+      (Dir.entries(@path) - %w(. .. ca.crt)).each do |entry|
+        certificate_path = File.join(@path, entry)
+        self << CertificateDepot::Certificate.from_file(certificate_path)
+      end
+    end
+    
+    include Enumerable
+    
+    def each(&block)
+      @certificates.each(&block)
+    end
+  end
+end

data/lib/certificate_depot/worker.rb

@@ -0,0 +1,161 @@
+class CertificateDepot
+  # A worker runs in a separate process created by the server. It hangs around
+  # and polls the server socket for incoming connections. Once it finds one it
+  # tried to process it.
+  #
+  # The worker has a lifeline to the server. The lifeline is a pipe used to
+  # signal the server. When the worker goes down the server can detect the
+  # severed lifeline. If the worker needs the server to stop sleeping it can
+  # write to the lifeline.
+  class Worker
+    attr_accessor :server, :lifeline
+    
+    # Creates a new worker instance. The first argument is a server instance.
+    def initialize(server)
+      @server  = server
+      @signals = []
+    end
+    
+    # Generates a new client certificate and writes it to the socket
+    def generate(socket, distinguished_name)
+      attributes = {
+        :type    => :client,
+        :subject => distinguished_name
+      }
+      keypair, certificate = server.depot.generate_keypair_and_certificate(attributes)
+      socket.write keypair.private_key.to_s
+      socket.write certificate.certificate.to_s
+    end
+    
+    # Writes help to the socket about a topic or a list of commands
+    def help(socket, command)
+      if command
+        socket.write(self.class.help(command.downcase))
+      else
+        socket.write("generate help shutdown\n")
+      end
+    end
+    
+    # Runs a command and writes the result to the request socket.
+    def run_command(socket, *args)
+      args    = args.dup
+      command = args.shift
+      
+      case command
+      when :generate
+        generate(socket, args[0])
+      when :help
+        help(socket, args[0])
+      when :shutdown
+        exit 1
+      end
+    end
+    
+    # Processes an incoming request. Parse the command, run the command, and
+    # close the socket.
+    def process_incoming_socket(socket, address)
+      input = socket.gets
+      server.log.debug("Got input: #{input.strip}")
+      run_command(socket, *self.class.parse_command(input))
+      socket.close
+    end
+    
+    # Starts the mainloop for the worker. The mainloop sleeps until one of the
+    # following three things happens: server gets a new request, activity on
+    # the lifeline to the server, or 2 seconds go by.
+    def run
+      trap_signals
+      loop do
+        break if signals_want_shutdown
+        begin
+          # IO.select returns either a triplet of lists with IO objects that
+          # need attention or nil on timeout of 2 seconds.
+          if needy = IO.select([server.socket, lifeline], nil, [server.socket, lifeline], 2)
+            server.log.debug("Detected activity on: #{needy.inspect}")
+            # If the lifeline is active the server went down and we need to go
+            # down as well.
+            break if needy.flatten.any? { |io| !io.respond_to?(:accept_nonblock) }
+            # Otherwise we handle incoming requests
+            needy.flatten.each do |io|
+              if io.respond_to?(:accept_nonblock)
+                begin
+                  process_incoming_socket(*io.accept_nonblock)
+                rescue Errno::EAGAIN, Errno::ECONNABORTED
+                end
+              end
+            end
+          end
+        rescue EOFError, Errno::EAGAIN, Errno::EINTR, Errno::EBADF, IOError
+        end
+      end
+      cleanup
+    end
+    
+    # Cleanup all worker resources
+    def cleanup
+      server.log.info("Shutting down")
+      begin
+        lifeline.close
+      rescue Errno::EPIPE
+      end
+    end
+    
+    # Installs signal traps to listen for incoming signals to the process.
+    def trap_signals
+      trap(:QUIT) { @signals << :QUIT }
+      trap(:EXIT) { @signals << :EXIT }
+    end
+    
+    # Returns true when the signals received by the process demand a shutdown
+    def signals_want_shutdown
+      !@signals.empty?
+    end
+    
+    # Parses a command issues by a client.
+    def self.parse_command(command)
+      parts = command.split(' ')
+      parts[0] = parts[0].intern if parts[0]
+      
+      case parts[0]
+      when :generate
+        parts[1] = OpenSSL::X509::Name.parse(parts[1].to_s) if parts[1]
+      when :revoke
+        parts[1] = parts[1].to_i if parts[1]
+      end
+      
+      parts
+    end
+    
+    # Returns help text for a certain command
+    def self.help(command)
+      case command
+      when 'generate'
+"GENERATE
+  generate <distinguished name>
+RETURNS
+  A private key and certificate in PEM format.
+EXAMPLE
+  generate /UID=12/CN=Bob Owner,emailAddress=bob@example.com
+"
+      when 'help'
+"HELP
+  help <command>
+RETURNS
+  A description of the command.
+EXAMPLE
+  help generate
+"
+      when 'shutdown'
+"SHUTDOWN
+  shutdown
+RETURNS
+  Kills the current worker handling the request.
+EXAMPLE
+  shutdown
+"
+      else
+        "Unknown command #{command}"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: certificate-depot
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Manfred Stienstra
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-27 00:00:00 +02:00
+default_executable: depot
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: test-spec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Certificate depot is a mini Certification Authority for TLS client certificates.
+email: manfred@fngtps.com
+executables: 
+- depot
+extensions: []
+
+extra_rdoc_files: 
+- TODO
+files: 
+- bin/depot
+- lib/certificate_depot.rb
+- lib/certificate_depot/certificate.rb
+- lib/certificate_depot/keypair.rb
+- lib/certificate_depot/log.rb
+- lib/certificate_depot/runner.rb
+- lib/certificate_depot/server.rb
+- lib/certificate_depot/store.rb
+- lib/certificate_depot/worker.rb
+- TODO
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Certificate depot is a mini Certification Authority for TLS client certificates.
+test_files: []
+