autosign 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d43769ea221d92c48e517138ec7a3c1ba16ed3a
-  data.tar.gz: 0a8454928712134b07dfaa5aa16c4451042086ac
+  metadata.gz: df93f6a505859c956b527410ffd01c67f3aad762
+  data.tar.gz: f9a1c7f7e857e6f596e6a50b4f534b772a1e62af
 SHA512:
-  metadata.gz: fd1b62abf9b19f6806a356a693c42eb91593ca9cad9bcc79240b7df3d01d1b72bc92c6b8cb14647f92cb92a59179831aa7a90e6d379274b536c977b65a844fd1
-  data.tar.gz: 4d5660957738acf9edd0413efab0c1fcc029ecc23ba049d75c26807a7e68f2310d5f5e22054a3c1469ab6e8609ec796ce1956968f6445bfb6e28ff3d990eda74
+  metadata.gz: 86adf30615877ec93e1038b51bf59b73026d01e842c93cdcc7b834965f7de546b8cded69e23d10917a393b0633650899c0460d3b3b60fcd1bb9cf9f5e76e39ff
+  data.tar.gz: 0d2b232814a18fef940e3605d83148a45d724c22ca3f7e490dbf14550ef4d67fbf0ef6eb3281ef35e9ad9fce8ff429ca88bb9d546071208d54fef405bd72229b

data/.travis.yml

@@ -0,0 +1,13 @@
+---
+language: ruby
+before_install: rm Gemfile.lock || true
+cache: bundler
+sudo: false
+rvm:
+  - 1.9.3
+  - jruby-19mode
+  - 2.0.0
+  - 2.1.5
+  - 2.2.2
+script:
+  - bundle exec cucumber

data/Gemfile.lock

@@ -5,14 +5,15 @@ PATH
       deep_merge
       gli (~> 2)
       iniparse (~> 1)
+      json
       jwt (~> 1)
       logging
       require_all
+      yard
 
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (2.2.8)
     aruba (0.6.2)
       childprocess (>= 0.3.6)
       cucumber (>= 1.1.1)
@@ -31,17 +32,12 @@ GEM
       gherkin (~> 2.12.0)
     deep_merge (1.0.1)
     diff-lcs (1.2.5)
-    facter (2.2.0)
-      CFPropertyList (~> 2.2.6)
     ffi (1.9.9)
     gherkin (2.12.2)
       multi_json (~> 1.3)
     gli (2.13.1)
-    hiera (1.3.4)
-      json_pure
     iniparse (1.4.0)
     json (1.8.3)
-    json_pure (1.8.1)
     jwt (1.5.1)
     little-plugger (1.1.3)
     logging (2.0.0)
@@ -49,10 +45,6 @@ GEM
       multi_json (~> 1.10)
     multi_json (1.11.1)
     multi_test (0.1.2)
-    puppet (3.7.0)
-      facter (> 1.6, < 3)
-      hiera (~> 1.0)
-      json_pure
     rake (10.4.2)
     rdoc (4.2.0)
       json (~> 1.4)
@@ -61,6 +53,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.3.0)
     rspec-support (3.3.0)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -68,6 +61,6 @@ PLATFORMS
 DEPENDENCIES
   aruba
   autosign!
-  puppet
+  cucumber
   rake
   rdoc

data/README.md

@@ -0,0 +1,8 @@
+# autosign
+[![Build Status](https://travis-ci.org/danieldreier/autosign.svg?branch=master)](https://travis-ci.org/danieldreier/autosign) [![Code Climate](https://codeclimate.com/github/danieldreier/autosign/badges/gpa.svg)](https://codeclimate.com/github/danieldreier/autosign) [![Dependency Status](https://gemnasium.com/danieldreier/autosign.svg)](https://gemnasium.com/danieldreier/autosign) [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/danieldreier/autosign) [![Inline docs](http://inch-ci.org/github/danieldreier/autosign.png)](http://inch-ci.org/github/danieldreier/autosign)
+
+Tooling to make puppet autosigning easy, secure, and extensible
+
+### Introduction
+
+This tool provides a CLI for performing puppet policy-based autosigning using JWT tokens. Read more at https://danieldreier.github.io/autosign.

data/autosign.gemspec

@@ -19,11 +19,14 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency('rake')
   s.add_development_dependency('rdoc')
   s.add_development_dependency('aruba')
+  s.add_development_dependency('cucumber')
   s.add_development_dependency('puppet')
   s.add_runtime_dependency('gli','~> 2')
   s.add_runtime_dependency('jwt','~> 1')
   s.add_runtime_dependency('iniparse','~> 1')
   s.add_runtime_dependency('logging')
+  s.add_runtime_dependency('json')
   s.add_runtime_dependency('deep_merge')
   s.add_runtime_dependency('require_all')
+  s.add_runtime_dependency('yard')
 end

data/bin/autosign-validator

@@ -16,14 +16,15 @@ certname = ARGV[0]
 @logger.debug "certname is " + certname
 
 @logger.debug "reading CSR from stdin"
-csr = Autosign::Decoder.decode_csr($stdin.read)
+raw_csr = $stdin.read
+csr = Autosign::Decoder.decode_csr(raw_csr)
 exit 1 unless csr.is_a?(Hash)
 
 @logger.debug "CSR: " + csr.to_s
 ### End Inputs
 
 ### validate token
-token_validation = Autosign::Validator.any_validator(csr[:challenge_password].to_s, certname.to_s)
+token_validation = Autosign::Validator.any_validator(csr[:challenge_password].to_s, certname.to_s, raw_csr)
 ### end validation
 
 ### Exit with correct exit status

data/features/validate.feature

@@ -9,7 +9,9 @@ Feature: Validate autosign key
       | AUTOSIGN_TESTMODE      | true   |
       | AUTOSIGN_TEST_SECRET   | secret |
       | AUTOSIGN_TEST_LOGLEVEL | info   |
-    When I run `autosign-validator i-7672fe81` interactively
+      | AUTOSIGN_TEST_JOURNALFILE | /tmp/autosign_journal |
+    When I run `rm -f /tmp/autosign_journal`
+     And I run `autosign-validator i-7672fe81` interactively
      And I pipe in the file "../../fixtures/i-7672fe81.pem"
     Then the output should contain "token validated successfully"
     Then the exit status should be 0

data/lib/autosign.rb

@@ -1,3 +1,5 @@
+require 'rubygems'
+require 'json'
 require 'autosign/version.rb'
 require 'autosign/token.rb'
 require 'autosign/config.rb'

data/lib/autosign/config.rb

@@ -1,45 +1,73 @@
+require 'iniparse'
+require 'rbconfig'
+require 'securerandom'
+require 'deep_merge'
+
 module Autosign
+  # Exceptions namespace for Autosign class
   module Exceptions
+    # Exception representing a general failure during validation
     class Validation < Exception
     end
+    # Exception representing a missing file during config validation
     class NotFound < Exception
     end
+    # Exception representing a permissions error during config validation
     class Permissions < Exception
     end
+    # Exception representing errors that Autosign does not know how to handle
     class Error < Exception
     end
   end
-    require 'iniparse'
-    require 'rbconfig'
-    require 'securerandom'
-    require 'deep_merge'
+
   class Config
-    attr_accessor :location
-    attr_accessor :config_file_paths
-    def initialize(settings = {})
+    # Create a config instance to interact with configuration settings
+    # To specify a configuration file, settings_param should include something like:
+    # {'config_file' => '/usr/local/etc/autosign.conf'}
+    #
+    # If no defaults are provided, the class checks several common locations for config file path.
+    #
+    # @param settings_param [Hash] config settings that should override defaults and config file settings
+    # @return [Autosign::Config] instance of the Autosign::Config class
+    def initialize(settings_param = {})
       # set up logging
       @log = Logging.logger['Autosign::Config']
       @log.debug "initializing Autosign::Config"
 
       # validate parameter
-      raise 'settings is not a hash' unless settings.is_a?(Hash)
+      raise 'settings is not a hash' unless settings_param.is_a?(Hash)
 
       # look in the following places for a config file
       @config_file_paths = ['/etc/autosign.conf', '/usr/local/etc/autosign.conf', File.join(Dir.home, '.autosign.conf')]
-      @config_file_paths = [ settings['config_file'] ] unless settings['config_file'].nil?
+      @config_file_paths = [ settings_param['config_file'] ] unless settings_param['config_file'].nil?
 
-      @settings = settings
+      @settings = settings_param
       @log.debug "Using merged settings hash: " + @settings.to_s
     end
 
+    # Return a merged settings hash of defaults, config file settings
+    # and passed in settings (such as from the CLI)
+    #
+    # @return [Hash] deep merged settings hash
     def settings
       @log.debug "merging settings"
       setting_sources = [default_settings, configfile, @settings]
-      setting_sources.inject({}) { |merged, hash| merged.deep_merge(hash) }
+      merged_settings = setting_sources.inject({}) { |merged, hash| merged.deep_merge(hash) }
+      @log.debug "using merged settings: " + merged_settings.to_s
+      return merged_settings
     end
 
     private
 
+    # default settings hash for the whole autosign gem
+    # the format must map to something an ini file can represent, so the
+    # structure should have a top-level key named "general" and key-value pairs
+    # below it, with strings as keys and strings or integers as values.
+    #
+    # validator settings should not be here; put those in the validator's
+    # default settings method.
+    #
+    # @return [Hash] default configuration settings
     def default_settings
       { 'general' =>
         {
@@ -54,6 +82,10 @@ module Autosign
       }
     end
 
+    # Locate the configuration file, parse it from INI-format, and return
+    # the results as a hash. Returns an empty hash if no config file is found.
+    #
+    # @return [Hash] configuration settings loaded from INI file
     def configfile
       @log.debug "Finding config file"
       @config_file_paths.each { |file|
@@ -71,6 +103,11 @@ module Autosign
       return {}
     end
 
+    # Validate configuration file
+    # Raises an exception if the config file cannot be validated
+    #
+    # @param configfile [String] the absolute path of the config file to validate
+    # @return [String] the absolute path of the config file
     def validate_config_file(configfile = location)
       @log.debug "validating config file"
       unless File.file?(configfile)
@@ -87,6 +124,9 @@ module Autosign
       configfile
     end
 
+    # Generate a default configuration file
+    # As a convenience for the user, we can generate a default config file
+    # This class is currently too tightly coupled with the JWT token validator
     def self.generate_default()
       os_defaults = (
         case RbConfig::CONFIG['host_os']

data/lib/autosign/decoder.rb

@@ -1,7 +1,9 @@
-require 'logging'
-
 module Autosign
   class Decoder
+    # Extract common name and challenge_password OID from X509 SSL Certificate signing requests
+    #
+    # @param csr[String] X509 format CSR
+    # @return [Hash] hash containing :challenge_password and :common_name keys
     def self.decode_csr(csr)
       @log = Logging.logger['Autosign::Decoder']
       @log.debug "decoding CSR"

data/lib/autosign/journal.rb

@@ -1,73 +1,45 @@
 require 'logging'
 require 'yaml/store'
 
-# Autosign::Journal checks for one-time keys that have been used before
 
 module Autosign
+# Autosign::Journal tracks one-time keys to prevent key re-use.
+# Keys are stored in the journal file by UUID.
+# The journal uses ruby's yaml/store, which is a YAML version of the PStore
+# data store. It is multi-process safe, and blocks until transactions in other
+# processes are complete.
   class Journal
+    #@return [Hash] settings of the autosign journal instance, such as the location of the journal file
     attr_accessor :settings
+
+    # @param settings [Hash] config settings for the new journal instance
+    # @return [Autosign::Journal] instance of the Autosign::Journal class
     def initialize(settings = {})
       @log = Logging.logger['Autosign::Journal']
       @log.debug "initializing Autosign::Journal"
       @settings = settings
-      fail unless self.setup
-    end
-
-    def setup
-      journalfile = self.settings['journalfile']
-      store = YAML::Store.new(journalfile, true)
-      store.ultra_safe = true
-      return store
-    end
-
-    # Check whether a UUID already exists in the journal
-    #
-    # ==== Attributes
-    #
-    # * +uuid+ - Unique journal entry identifier
-    #
-    # ==== Examples
-    #
-    # To exit if a token has already been used:
-    #
-    #    journal = Autosign::Journal.new({journalfile = '/etc/autosign/journal')
-    #    exit 1 if journal.check('d2e601c8-93df-4459-be18-1877eaf00920')
-    def check(uuid)
-      fail unless validate_uuid(uuid)
-      true
+      fail unless setup
     end
 
-    def delete(uuid)
-      fail unless validate_uuid(uuid)
-      true
-    end
 
 
-    # Add a new token to the journal
-    #
-    # ==== Attributes
-    #
-    # * +uuid+ - Unique journal entry identifier
-    # * +validto+ - Integer seconds unix timestamp that the token will be valid until
-    # * +data+ - Arbitrary hash that will be serialized and stored in the journal for auditing purposes
+    # Add a new token to the journal. Only succeeds if the token is not in the journal already.
     #
-    # ==== Examples
+    # @param uuid [String] RFC4122 v4 UUID functioning as unique journal entry identifier
+    # @param validto [Integer] POSIX timestamp in seconds since epoch that the token will be valid until
+    # @param data [Hash] Arbitrary hash that will be serialized and stored in the journal for auditing purposes
     #
-    # To attempt adding a token to the journal:
-    #
-    #    journal = Autosign::Journal.new({journalfile = '/etc/autosign/journal')
-    #    exit 1 if journal.add('d2e601c8-93df-4459-be18-1877eaf00920')
+    # @example attempt adding a token to the journal
+    #   journal = Autosign::Journal.new({journalfile = '/etc/autosign/journal')
+    #   fail unless journal.add('d2e601c8-93df-4459-be18-1877eaf00920')
     #
     # This will only succeed if the token has not previously been added
     # This is the primary way this class is expected to be used
     def add(uuid, validto, data = {})
       @log.debug "attempting to add UUID: '#{uuid.to_s}' which is valid to '#{Time.at(validto.to_i)}' with data #{data.to_s}"
       puts validate_uuid(uuid).to_s
-      #fail unless validate_uuid(uuid)
-      #fail unless validate_timestamp(validto)
-      #fail unless validate_data(data)
 
-      store = self.setup
+      store = setup
       # wrap the change in a transaction because multiple autosign instances
       # may try to run simultaneously. This will block until another process
       # releases the transaction lock.
@@ -86,6 +58,22 @@ module Autosign
       return !!result
     end
 
+    private
+
+    # Create a new journal file, or load an existing one if it already exists.
+    # @return [YAML::Store] instance of YAML::Store using the configured journal file.
+    def setup
+      @log.debug "using journalfile: " + self.settings['journalfile']
+      journalfile = self.settings['journalfile']
+      store = YAML::Store.new(journalfile, true)
+      store.ultra_safe = true
+      return store
+    end
+
+    # Verify that a string is a V4 UUID
+    #
+    # @param uuid [String] RFC4122 v4 UUID
+    # @return [Boolean] true if the uuid string is a valid UUID, false if not a valid UUID
     def validate_uuid(uuid)
       unless uuid.is_a?(String)
         @log.error "UUID is not a string"
@@ -96,6 +84,7 @@ module Autosign
         @log.error "UUID is not a valid V4 UUID"
         return false
       end
+      return true
     end
 
     def validate_data(data)

data/lib/autosign/token.rb

@@ -1,17 +1,36 @@
 module Autosign
   require 'jwt'
-  require 'JSON'
+  require 'json'
   require 'securerandom'
 
+  # Class modeling JSON Web Tokens as credentials for certificate auto signing.
+  # See http://jwt.io for more information about JSON web tokens in general.
+  #
+  # @return [Autosign::Token] instance of the Autosign::Token class
   class Token
+    # @return [Integer, String] seconds that the token will be valid for after being issued
     attr_reader :validfor
+    # @return [String] common name or regex of common names for which this token is valid
     attr_reader :certname
+    # @return [True, False] true if the token can be used multiple times, false if the token is intended as a one-time credential
     attr_reader :reusable
+    # @return [String] arbitrary string identifying the person or machine that generated the token initially
     attr_reader :requester
+    # @return [String] shared HMAC secret used to sign or validate tokens
     attr_reader :secret
+    # @return [Integer, String] POSIX seconds since epoch that the token is valid until
     attr_accessor :validto
+    # @return [String] RFC4122 v4 UUID functioning as unique identifier for the token
     attr_accessor :uuid
 
+    # Create a token instance to model an individual JWT token
+    #
+    # @param certname [String] common name or regex of common names for which this token is valid
+    # @param reusable [True, False] true if the token can be used multiple times, false if the token is intended as a one-time credential
+    # @param validfor [Integer, String] seconds that the token will be valid for, starting at the current time
+    # @param requester [String] arbitrary string identifying the person or machine that generated the token initially
+    # @param secret [String] shared HMAC secret used to sign or validate tokens
+    # @return [Autosign::Config] instance of the Autosign::Config class
     def initialize(certname, reusable=false, validfor=7200, requester, secret)
       # set up logging
       @log = Logging.logger['Autosign::Token']
@@ -26,6 +45,16 @@ module Autosign
       @validto   = Time.now.to_i + self.validfor
     end
 
+    # Validate an existing JSON Web Token.
+    #
+    # 1. Use the HMAC secret to validate the data in the token
+    # 2. Compare the expiration time in the token to the current time to determine if it's valid
+    # 3. compare the certname or regex of certnames in the token to the requested common name from the certificate signing request
+    #
+    # @param requested_certname [String] common name coming from the certificate signing request. This is the common name the requester wants.
+    # @param token [String] JSON Web Token coming from the certificate signing request
+    # @param hmac_secret [String] Password that the token was (hopefully) originally signed with.
+    # @return [True, False] returns true if the token can be validated, or false if the token cannot be validated.
     def self.validate(requested_certname, token, hmac_secret)
       @log = Logging.logger['Autosign::Token.validate']
       @log.debug "attempting to validate token"
@@ -69,15 +98,29 @@ module Autosign
       raise Autosign::Token::ValidationError
     end
 
-    def self.token_validto(token, hmac_secret)
-      begin
-        decoded = JWT.decode(token, hmac_secret)[0]
-      rescue JWT::ExpiredSignature
-        raise Autosign::Token::ExpiredToken
-      rescue
-        raise Autosign::Token::Invalid
-      end
-      return decoded['exp'].to_i
+    # check if the token is reusable or a one-time use token
+    # @return [True, False] return true if the token can be used multiple times, false if the token can only be used once
+    def reusable
+      !!@reusable
+    end
+
+    # convert the token to a hash
+    # @return [Hash{String => String}]
+    def to_hash
+      {
+        "certname"  => certname,
+        "requester" => requester,
+        "reusable"  => reusable,
+        "validfor"  => validfor,
+        "uuid"      => uuid
+      }
+    end
+
+    # Sign the token with HMAC using a SHA-512 hash
+    # @return [String] signed, serialized JSON web token
+    def sign()
+      exp_payload = { :data => to_json, :exp => validto.to_s}
+      JWT.encode exp_payload, secret, 'HS512'
     end
 
     def self.from_token(token, hmac_secret)
@@ -100,6 +143,23 @@ module Autosign
       return new_token
     end
 
+    # Extract the expiration time, in seconds since epoch, from a signed token. Uses HMAC secret to validate the expiration time.
+    # @param token [String] Serialized JSON web token
+    # @param hmac_secret [String] Password that the token was (hopefully) originally signed with.
+    # @return [Integer] POSIX time (seconds since epoch) that the token is valid until
+    def self.token_validto(token, hmac_secret)
+      begin
+        decoded = JWT.decode(token, hmac_secret)[0]
+      rescue JWT::ExpiredSignature
+        raise Autosign::Token::ExpiredToken
+      rescue
+        raise Autosign::Token::Invalid
+      end
+      return decoded['exp'].to_i
+    end
+
+    private
+
     def certname=(str)
       @name = str
     end
@@ -108,10 +168,6 @@ module Autosign
       @reusable = !!bool
     end
 
-    def reusable
-      !!@reusable
-    end
-
     def requester=(str)
       @requester = str
     end
@@ -120,23 +176,8 @@ module Autosign
       @secret = str
     end
 
-    def to_hash
-      {
-        "certname"  => self.certname,
-        "requester" => self.requester,
-        "reusable"  => self.reusable,
-        "validfor"  => self.validfor,
-        "uuid"      => self.uuid
-      }
-    end
-
     def to_json
-      JSON.generate self.to_hash
-    end
-
-    def sign()
-      exp_payload = { :data => self.to_json, :exp => self.validto.to_s}
-      JWT.encode exp_payload, self.secret, 'HS512'
+      JSON.generate to_hash
     end
 
   end

data/lib/autosign/validator.rb

@@ -2,13 +2,44 @@ require 'logging'
 require 'require_all'
 
 module Autosign
+  # Parent class for validation backends. Validators take the
+  # challenge_password and common name from a certificate signing request,
+  # and perform some action to determine whether the request is valid.
+  #
+  # Validators also get the raw X509 CSR in case the extracted information
+  # is insufficient for future, more powerful validators.
+  #
+  # All validators must inherit from this class, and must override several
+  # methods in order to function. At a minimum, the name and perform_validation
+  # methods must be implemented by child classes.
+  #
+  # @return [Autosign::Validator] instance of the Autosign::Validator class
   class Validator
     def initialize()
-      @log = Logging.logger[self.name]
+      start_logging()
       settings() # just run to validate settings
       setup()
+      # call name to ensure that the class fails immediately if child classes
+      # do not implement it.
+      name()
     end
 
+    # Name of the validator. This must be implemented by validators which
+    # inherit from the Autosign::Validator class. The name is used to identify
+    # the validator in friendly messages and to determine which configuration
+    # file section settings will be loaded from.
+    #
+    # @example set the name of a child class validator to "example"
+    #    module Autosign
+    #      module Validators
+    #        class Example < Autosign::Validator
+    #          def name
+    #           "example"
+    #          end
+    #        end
+    #      end
+    #    end
+    # @return [String] name of the validator. Do not use special characters.
     def name
       # override this after inheriting
       # should return a string with no spaces
@@ -16,12 +47,30 @@ module Autosign
       raise NotImplementedError
     end
 
-    def validate(challenge_password, certname)
+    # define how a validator actually validates the request.
+    # This must be implemented by validators which inherit from the
+    # Autosign::Validator class.
+    #
+    # @param challenge_password [String] the challenge_password OID from the certificate signing request. The challenge_password field is the same setting as the "challengePassword" field in a `csr_attributes.yaml` file when the CSR is generated. In a request using a JSON web token, this would be the serialized token.
+    # @param certname [String] the common name being requested in the certificate signing request. Treat the certname as untrusted. This is user-submitted data that you must validate.
+    # @param raw_csr [String] the encoded X509 certificate signing request, as received by the autosign policy executable. This is provided as an optional extension point, but your validator may not need to use it.
+    # @return [True, False] return true if the certificate should be signed, and false if you cannot validate the request successfully.
+    def perform_validation(challenge_password, certname, raw_csr)
+      # override this after inheriting
+      # should return true to indicate success validating
+      # or false to indicate that the validator was unable to validate
+      raise NotImplementedError
+    end
+
+    # wrapper method that wraps input validation and logging around the perform_validation method.
+    # Do not override or use this class in child classes. This is the class that gets called
+    # on validator objects.
+    def validate(challenge_password, certname, raw_csr)
       @log.debug "running validate"
       fail unless challenge_password.is_a?(String)
       fail unless certname.is_a?(String)
 
-      case perform_validation(challenge_password, certname)
+      case perform_validation(challenge_password, certname, raw_csr)
       when true
         @log.debug "validated successfully"
         @log.info  "Validated '#{certname}' using '#{name}' validator"
@@ -36,18 +85,27 @@ module Autosign
       end
     end
 
-    def self.any_validator(challenge_password, certname)
+    # Class method to attempt validation of a request against all validators which inherit from this class.
+    # The request is considered to be validated if any one validator succeeds.
+    # @param challenge_password [String] the challenge_password OID from the certificate signing request
+    # @param certname [String] the common name being requested in the certificate signing request
+    # @param raw_csr [String] the encoded X509 certificate signing request, as received by the autosign policy executable
+    # @return [True, False] return true if the certificate should be signed, and false if it cannot be validated
+    def self.any_validator(challenge_password, certname, raw_csr)
       @log = Logging.logger[self.name]
       # iterate over all known validators and attempt to validate using them
+      results_by_validator = {}
       results = self.descendants.map {|c|
         validator = c.new()
         @log.debug "attempting to validate using #{validator.name}"
-        result = validator.validate(challenge_password, certname)
+        result = validator.validate(challenge_password, certname, raw_csr)
+        results_by_validator[validator.name] = result
         @log.debug "result: #{result.to_s}"
         result
       }
       @log.debug "validator results: " + results.to_s
-      success = results.inject(true) { |sum, n| n and sum }
+      @log.info "results by validator: " + results_by_validator.to_s
+      success = results.any?{|result| result == true}
       if success
         @log.info "successfully validated using one or more validators"
         return true
@@ -58,14 +116,18 @@ module Autosign
     end
 
     private
-    def perform_validation(challenge_password, certname)
-      # override this after inheriting
-      # should return true to indicate success validating
-      # or false to indicate that the validator was unable to validate
-      raise NotImplementedError
+
+    # this is automatically called when the class is initialized; do not
+    # override it in child classes.
+    def start_logging
+      @log = Logging.logger["Autosign::Validator::" + self.name.to_s]
+      @log.debug "starting autosign validator: " + self.name.to_s
     end
 
-    # perform any steps you want to take during initialization
+    # (optionally) override this method in validator child classes to perform any additional
+    # setup during class initialization prior to beginning validation.
+    # If you need to create a database connection, this would be a good place to do it.
+    # @return [True, False] return true if setup succeeded, or false if setup failed and the validation should not continue
     def setup
       true
     end
@@ -74,9 +136,19 @@ module Autosign
       ObjectSpace.each_object(Class).select { |klass| klass < self }
     end
 
+    # provide a merged settings hash of default settings for a validator,
+    # config file settings for the validator, and override settings defined in
+    # the validator.
+    #
+    # Do not override this in child classes. If you need to set
+    # custom config settings, override the get_override_settings method.
+    # The section of the config file this reads from is the same as the name
+    # method returns.
+    #
+    # @return [Hash] of config settings
     def settings
       @log.debug "merging settings"
-      setting_sources = [default_settings, load_config, get_override_settings]
+      setting_sources = [get_override_settings, load_config, default_settings]
       merged_settings = setting_sources.inject({}) { |merged, hash| merged.deep_merge(hash) }
       @log.debug "using merged settings: " + merged_settings.to_s
       @log.debug "validating merged settings"
@@ -90,28 +162,37 @@ module Autosign
       end
     end
 
-    # this hash will be merged with the configuration section's hash
-    # override this when inheriting if you need to set config defaults
+    # (optionally) override this from a child class to set config defaults.
+    # These will be overridden by config file settings.
+    #
+    # Override this when inheriting if you need to set config defaults.
+    # For example, if you want to pull settings from zookeeper, this would
+    # be a good place to do that.
+    #
+    # @return [Hash] of config settings
     def default_settings
       {}
     end
 
 
-    # override this to perform validation checks on the merged config hash
-    # of default settings, config file settings, and override settings.
-    # return either true or false
+    # (optionally) override this to perform validation checks on the merged
+    # config hash of default settings, config file settings, and override
+    # settings.
+    # @return [True, False]
     def validate_settings(settings)
       settings.is_a?(Hash)
     end
 
-    # load any required configuration
+    # load any required configuration from the config file.
+    # Do not override this in child classes.
+    # @return [Hash] configuration settings from the validator's section of the config file
     def load_config
       @log.debug "loading validator-specific configuration"
       config = Autosign::Config.new
 
       if config.settings.to_hash[self.name].nil?
-        @log.warning "Unable to load validator-specific configuration"
-        @log.warning "Cannot load configuration section named '#{self.name}'"
+        @log.warn "Unable to load validator-specific configuration"
+        @log.warn "Cannot load configuration section named '#{self.name}'"
         return {}
       else
         @log.debug "Set validator-specific settings from config file: " + config.settings.to_hash[self.name].to_s
@@ -119,8 +200,11 @@ module Autosign
       end
     end
 
-    # this hook gets run to get settings from the CLI etc
-    # this is how you override defaults and config file settings
+    # (optionally) override this from child classes to get custom configuration
+    # from a validator.
+    #
+    # This is how you override defaults and config file settings.
+    # @return [Hash] configuration settings
     def get_override_settings
       {}
     end

data/lib/autosign/validators/jwt.rb

@@ -7,7 +7,7 @@ module Autosign
 
       private
 
-      def perform_validation(token, certname)
+      def perform_validation(token, certname, raw_csr)
         puts "attempting to validate JWT token"
         return false unless Autosign::Token.validate(certname, token, settings['secret'])
         puts "validated JWT token"
@@ -24,6 +24,7 @@ module Autosign
 
       def add_to_journal(token)
         validated_token = Autosign::Token.from_token(token, settings['secret'])
+        @log.debug 'add_to_journal settings: ' + settings.to_s
         journal = Autosign::Journal.new({'journalfile' => settings['journalfile']})
         token_expiration = Autosign::Token.token_validto(token, settings['secret'])
 
@@ -44,7 +45,17 @@ module Autosign
       end
 
       def get_override_settings
-        {}
+        # this is a hack to make testing easier
+        if (ENV["AUTOSIGN_TESTMODE"] == "true" and
+            !ENV["AUTOSIGN_TEST_SECRET"].nil? and
+            !ENV["AUTOSIGN_TEST_JOURNALFILE"].nil? )
+           {
+             'secret'      => ENV["AUTOSIGN_TEST_SECRET"].to_s,
+             'journalfile' => ENV["AUTOSIGN_TEST_JOURNALFILE"].to_s
+           }
+        else
+          {}
+        end
       end
 
     def validate_settings(settings)

data/lib/autosign/validators/multiplexer.rb

@@ -0,0 +1,65 @@
+module Autosign
+  module Validators
+    class Multiplexer < Autosign::Validator
+      def name
+        "multiplexer"
+      end
+
+      private
+
+      def perform_validation(token, certname, raw_csr)
+        results = []
+        @log.debug "validating using multiplexed external executables"
+        policy_executables.each {|executable|
+          @log.debug "attempting to validate using #{executable.to_s}"
+          results << IO.popen(executable, 'r+') {|obj| obj.puts raw_csr; obj.close_write; obj.read; obj.close; $?.to_i }
+          @log.debug "exit code from #{executable.to_s}: #{results.last}"
+        }
+        bool_results = results.map {|val| val == 0}
+        return validate_using_strategy(bool_results)
+      end
+
+
+      def default_settings
+        {
+          'strategy' => 'any',
+        }
+      end
+
+    def validate_using_strategy(array)
+      case settings['strategy']
+      when 'any'
+        @log.debug "validating using 'any' strategy"
+        return array.any?
+      when 'all'
+        @log.debug "validating using 'all' strategy"
+        return array.all?
+      else
+        @log.error "unable to validate; unknown strategy"
+        return false
+      end
+    end
+
+    def policy_executables
+      return [] if settings['external_policy_executable'].nil?
+      exec_list = settings['external_policy_executable']
+      return [exec_list] if exec_list.is_a?(String)
+      return exec_list if exec_list.is_a?(Array)
+      return []
+    end
+
+
+    def validate_settings(settings)
+      @log.debug "validating settings: " + settings.to_s
+      unless ['any', 'all'].include? settings['strategy']
+        @log.error "strategy setting must be set to 'any' or 'all'"
+        return false
+      end
+
+      @log.debug "done validating settings"
+      true
+    end
+
+    end
+  end
+end

data/lib/autosign/version.rb

@@ -1,3 +1,3 @@
 module Autosign
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: autosign
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Your Name Here
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-13 00:00:00.000000000 Z
+date: 2015-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: puppet
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: deep_merge
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +178,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email: your@email.address.com
 executables:
@@ -159,8 +201,10 @@ extra_rdoc_files:
 - README.rdoc
 - autosign.rdoc
 files:
+- ".travis.yml"
 - Gemfile
 - Gemfile.lock
+- README.md
 - README.rdoc
 - Rakefile
 - autosign.gemspec
@@ -180,6 +224,7 @@ files:
 - lib/autosign/token.rb
 - lib/autosign/validator.rb
 - lib/autosign/validators/jwt.rb
+- lib/autosign/validators/multiplexer.rb
 - lib/autosign/version.rb
 homepage: http://your.website.com
 licenses: []