tlspretense 0.6.1

data/doc/linux_setup.rdoc

@@ -0,0 +1,64 @@
+= Setting Up Linux for Use With TLSPretense
+
+To run TLSPretense on Linux, you need a system that has two network interfaces.
+This Linux system could run from a virtual machine, or it could run on a laptop
+and use the laptop's wifi card as a wireless access point to test.
+
+The following setup will use a Linux host to run TLSPretense, and it will
+configure netfilter to be a NAT with statically managed IP address on its
+internal network.
+
+TODO: How to host a DHCP server on certain systems.
+
+== Configuring Linux to act as a NAT/router/gateway
+
+The first step is to configure the Linux system's routing with IPTables. The
+following script will turn the system into a NAT router. TLSPretense will then
+later add and remove iptables rules as needed in order to intercept network
+traffic during testing.
+
+In this script, we assume +eth0+ is the external interface that can connect to
+the original destination, and +eth1+ is the internal interface that the client
+system will connect to.
+
+    #!/bin/sh
+    external=eth0
+    internal=eth1
+
+    iptables --flush
+    iptables --table nat --flush
+    iptables --delete-chain
+    iptables --table nat --delete-chain
+
+
+    echo "Manually setup the internal network's nic"
+    ifconfig $internal 192.168.42.1 netmask 255.255.255.0 
+
+    echo "Enable packet forwarding"
+    echo 1 > /proc/sys/net/ipv4/ip_forward
+
+    echo "Apply basic iptables rules to create a NAT"
+    iptables -t nat -A POSTROUTING -o $external -j MASQUERADE
+
+    echo "Done! TLSPretense will automatically add and remove the rules for redirecting traffic."
+
+Here we choose 192.168.42.* as the internal network IP address range.
+
+Check to make sure that the TLSPretense host is able to access the internet
+over the external interface, and that it can look up hostnames.
+
+TODO: handling wireless ({although Mallory already has a
+guide}[https://bitbucket.org/IntrepidusGroup/mallory/wiki/Wifi_Hotspot_Setup])
+
+== Configure the Client's Host
+
+Next, the system that will run the client code needs to be configured to use
+the TLSPretense host as its gateway. This usually involves configuring the
+system's network connection with information like the following:
+
+    Address: 192.168.42.100
+    Gateway: 192.168.42.1
+    Subnet mask: 255.255.255.0
+
+You will also need to configure the client's DNS with a known good DNS server.
+

data/lib/certmaker.rb

@@ -0,0 +1,61 @@
+
+require 'fileutils'
+require 'yaml'
+require 'openssl'
+
+require 'certmaker/ext_core/hash_indifferent_fetch'
+require 'certmaker/certificate_factory'
+require 'certmaker/certificate_suite_generator'
+
+module CertMaker
+
+
+  # Generate certificates and keys using +config+.
+  #
+  # Config is usually a data structure derived from parsing a YAML file.
+  def make_certs(config, verbose=false)
+    FileUtils.mkdir_p config['certmaker']['outdir'], :verbose => verbose
+
+    certs = CertificateSuiteGenerator.new(config['certs'], config['hostname'], config['certmaker']).certificates
+
+    certs.each do |calias, ck|
+      File.open(File.join(config['certmaker']['outdir'],calias+"cert.pem"),"wb") { |f| f.write ck[:cert] }
+      File.open(File.join(config['certmaker']['outdir'],calias+"key.pem"),"wb") { |f| f.write ck[:key] }
+    end
+
+  end
+  module_function :make_certs
+
+  # Ensure that the custom ca exists.
+  def make_ca(config, verbose=false)
+    unless config['certmaker'].has_key? 'customgoodca'
+      puts "certmaker does not have a 'customgoodca' entry, so a CA will be regenerated every time."
+      return
+    end
+
+    cacert = config['certmaker']['customgoodca']['certfile']
+    cakey = config['certmaker']['customgoodca']['keyfile']
+
+    if File.exist? cacert and File.exist? cakey
+      puts "CA and CA's key already exist."
+    elsif File.exist? cacert and not File.exist? cakey
+      raise "CA certificate exists, but the key file does not exist?!"
+    elsif not File.exist? cacert and File.exist? cakey
+      raise "CA certificate does not exist, but the key file exists?!"
+    else
+      puts "Generating a new CA"
+      cacertdir = File.dirname(config['certmaker']['customgoodca']['certfile'])
+      FileUtils.mkdir_p cacertdir, :verbose => verbose
+      cakeydir = File.dirname(config['certmaker']['customgoodca']['keyfile'])
+      FileUtils.mkdir_p cakeydir, :verbose => verbose
+      csg = CertificateSuiteGenerator.new(config['certs'], config['hostname'], config['certmaker'])
+      csg.generate_certificate('goodca',config['certs']['goodca'])
+      cadata = csg.certificates['goodca']
+      File.open(cacert,"wb") { |f| f.write cadata[:cert] }
+      File.open(cakey,"wb") { |f| f.write cadata[:key] }
+      puts "New CA generated."
+      puts "Make sure you remove or comment out the passphrase in config.yml if you had one previously set!"
+    end
+  end
+  module_function :make_ca
+end

data/lib/certmaker/certificate_factory.rb

@@ -0,0 +1,106 @@
+module CertMaker
+  class CertificateFactory
+
+    attr_accessor :ca, :ca_key
+    attr_accessor :subject
+    attr_accessor :not_before, :not_after
+    attr_accessor :extensions
+    attr_accessor :key_type
+    attr_accessor :key_size
+    attr_accessor :signing_alg
+
+    def initialize
+      self.ca = :self
+      self.extensions = []
+      self.key_type = OpenSSL::PKey::RSA
+      self.key_size = 2048
+      self.signing_alg = :SHA1
+    end
+
+    # Handle special time values.
+    #
+    # now   Time.now
+    # 30    30 days from now
+    # -30   30 days before now
+    def derive_time(timeval)
+      if ['now',:now].include? timeval
+        Time.now
+      elsif timeval.kind_of? Numeric
+        Time.now + timeval*24*60*60
+      else
+        raise "Unhandled time value: #{timeval}"
+      end
+    end
+
+    # Returns an array containing the certificate and associated key with the configured attributes, plus with the
+    # overridden attrs.
+    def create(args={})
+
+      # Make a key
+      kt = args.indifferent_fetch(:key_type, self.key_type)
+      begin
+        kt = OpenSSL::PKey.const_get(kt)
+      rescue TypeError
+      end
+      nk = kt.new self.key_size
+
+      # Certificate basics
+      nc = OpenSSL::X509::Certificate.new
+      nc.version = 2
+      nc.serial = args.indifferent_fetch(:serial, 1)
+      nc.subject = OpenSSL::X509::Name.parse(args.indifferent_fetch(:subject, self.subject))
+      nc.public_key = nk.public_key
+
+      # "now" is a special time value
+      nc.not_before = derive_time(args.indifferent_fetch(:not_before,self.not_before))
+      nc.not_after = derive_time(args.indifferent_fetch(:not_after,self.not_after))
+
+      # Prep for extensions
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = nc
+
+      self.ca = args.indifferent_fetch(:ca,self.ca)
+      # Issuer handling
+      if ['self',:self].include? self.ca
+        nc.issuer = nc.subject
+        ef.issuer_certificate = nc
+        signing_key = nk
+      else
+        nc.issuer = self.ca.subject
+        ef.issuer_certificate = self.ca
+        signing_key = args.indifferent_fetch(:ca_key,self.ca_key)
+      end
+
+      # Copy the extensions (we don't want to modify the original array later)
+      exts = args.indifferent_fetch(:extensions, self.extensions).dup
+      # filter out blocked extension patterns
+      if args.indifferent_fetch(:blockextensions, false)
+        args.indifferent_fetch(:blockextensions, nil).each do |badext|
+          exts = exts.select { |ext| ext.scan(badext).empty? }
+        end
+      end
+      # add any additional extensions
+      exts.concat args.indifferent_fetch(:addextensions,[])
+
+      # Add the extensions
+      exts.each do |ext|
+        nc.add_extension(ef.create_ext_from_string(ext))
+      end
+
+      # Look up the signing algorithm. If it is set to a symbol or string,
+      # we'll be able to look up a class. Otherwise we assume that the current
+      # signing_alg is a class symbol.
+      sa = args.indifferent_fetch(:signing_alg, self.signing_alg)
+      begin
+        sa = OpenSSL::Digest.const_get(sa)
+      rescue TypeError
+      end
+
+      nc.sign(signing_key, sa.new)
+
+      return [nc, nk]
+    end
+
+  end
+
+end

data/lib/certmaker/certificate_suite_generator.rb

@@ -0,0 +1,120 @@
+
+module CertMaker
+  # Generates a suite of certificates from a configuration.
+  #
+  # Config should be a hash-like with each key being the alias to a hash-like
+  # that describes the certificate. Certificates can then refer to issuers or
+  # signing_keys by alias, and CertificateSuiteGenerator will ensure that they
+  # are generated in the correct order.
+  class CertificateSuiteGenerator
+    attr_accessor :certificates
+
+    # certinfos should be a hash-like where each entry describes a certificate.
+    # defaulthostname should be a string that will be inserted into %HOSTNAME%
+    # in certificate subject lines.
+    def initialize(certinfos, defaulthostname, config={})
+      @config = config
+      @defaulthostname = defaulthostname
+      @parenthostname = defaulthostname.sub(/^[\w-]+\./, '') # remove left-most label
+      @certinfos = certinfos
+      @certificates = {}
+    end
+
+    def certificates
+      generate_certificates if @certificates.empty?
+      @certificates
+    end
+
+    def generate_certificates
+      @certinfos.each_pair do |calias, certinfo|
+        puts ''
+        puts ''
+        puts calias
+        p certinfo
+        generate_certificate(calias, certinfo) unless @certificates.has_key? calias
+      end
+    end
+
+    def generate_certificate(calias, certinfo)
+      puts "Generating #{calias}..."
+
+      # Check for customgoodca.
+      if calias == 'goodca' and @config.has_key? 'customgoodca'
+        certfile = @config['customgoodca']['certfile']
+        keyfile = @config['customgoodca']['keyfile']
+        keypass = @config['customgoodca'].fetch('keypass',nil)
+        if File.exist? certfile and File.exist? keyfile
+          puts "Customgoodca defined and the CA's files exist. We will use it instead of generating a new goodca."
+          rawcert = File.read(certfile)
+          rawkey = File.read(keyfile)
+          goodcert = OpenSSL::X509::Certificate.new(rawcert)
+          goodkey = OpenSSL::PKey.read(rawkey, keypass)
+          @certificates[calias] = { :cert => goodcert, :key => goodkey }
+          return
+        else
+          puts "#{certfile} or #{keyfile} does not exist! We will generate a new one."
+        end
+      end
+
+      cf = CertificateFactory.new
+
+      # configure the issuer
+      if certinfo['issuer'] == 'self'
+        puts "self signed"
+        cf.ca = :self
+        cf.ca_key = :self
+      else
+        issueralias = certinfo['issuer']
+        puts "issued by #{issueralias.inspect}"
+        raise "Issuer #{issueralias} is not in the list of certificates!" unless @certinfos.has_key? issueralias
+        generate_certificate(issueralias,@certinfos[issueralias]) unless @certificates.has_key? issueralias
+        ca = @certificates[issueralias]
+        cf.ca = ca[:cert]
+        cf.ca_key = ca[:key] # Use the issuer's key...
+      end
+      # ... but override the signing key if it is explicitly specified.
+      if certinfo.has_key? 'signing_key'
+        signeralias = certinfo['signing_key']
+        puts "Signed by #{signeralias.inspect}"
+        raise "Signer #{signeralias} is not in the list of certificates!" unless @certinfos.has_key? signeralias
+        generate_certificate(signeralias,@certinfos[signeralias]) unless @certificates.has_key? signeralias
+        cf.ca_key = @certificates[signeralias][:key]
+      end
+      # doctor the certinfo's subject line and any extensions.
+      certinfo['subject'] = certinfo['subject'].gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname)
+      if certinfo.has_key? 'extensions'
+        certinfo['extensions'] = certinfo['extensions'].map { |ext| ext.gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname) }
+      end
+      if certinfo.has_key? 'addextensions'
+        certinfo['addextensions'] = certinfo['addextensions'].map { |ext| ext.gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname) }
+      end
+      # doctor the serial number.
+      if @config.has_key? 'missing_serial_generation'
+        unless certinfo.has_key? 'serial'
+          case @config['missing_serial_generation']
+          when "random"
+            certinfo['serial'] = randomserial
+          else
+            certinfo['serial'] = @config['missing_serial_generation']
+          end
+        end
+      end
+
+      cert, key = cf.create(certinfo)
+      puts "Created #{calias}"
+
+      @certificates[calias] = { :cert => cert, :key => key }
+    end
+
+    def randomserial
+      range = 2**30
+      begin
+        require 'securerandom'
+        SecureRandom.random_number range
+      rescue LoadError # no securerandom, so use weaker rand.
+        rand(range)
+      end
+    end
+
+  end
+end

data/lib/certmaker/ext_core/hash_indifferent_fetch.rb

@@ -0,0 +1,12 @@
+
+class Hash
+  # Light extension to hash to add indifferent fetching. Meant to be more
+  # lightweight than depending on ActiveSupport for HashWithIndifferentAccess.
+  def indifferent_fetch(key, *extra)
+    if key.class == Symbol
+      self.fetch(key, self.fetch(key.to_s, *extra))
+    else
+      self.fetch(key, self.fetch(key.to_sym, *extra))
+    end
+  end
+end

data/lib/certmaker/runner.rb

@@ -0,0 +1,27 @@
+require 'certmaker'
+require 'yaml'
+require 'fileutils'
+
+module CertMaker
+  class Runner
+    include FileUtils
+
+    #Checks for a CA, and generates it if needed.
+    def ca
+      y = YAML.load_file('config.yml')
+      CertMaker.make_ca y
+    end
+
+    #Generate a suite of test certificates
+    def certs
+      ca
+      y = YAML.load_file('config.yml')
+      CertMaker.make_certs y
+    end
+
+    #Clean up by deleting the 'certs' directory.
+    def clean
+      rm_r "certs"
+    end
+  end
+end

data/lib/certmaker/tasks.rb

@@ -0,0 +1,20 @@
+
+namespace :certs do
+
+  desc "Checks for a CA, and generates it if needed."
+  task :ca do
+    require 'certmaker/runner'
+    CertMaker::Runner.new.ca
+  end
+
+  desc "Generate a suite of test certificates"
+  task :generate => [ 'certs:ca' ] do
+    require 'certmaker/runner'
+    CertMaker::Runner.new.certs
+  end
+
+  desc "Clean up by deleting the 'certs' directory."
+  task :clean do
+    rm_r "certs"
+  end
+end

data/lib/packetthief.rb

@@ -0,0 +1,167 @@
+require 'socket'
+require 'logger'
+
+require 'eventmachine'
+
+# Framework for intercepting packets, redirecting them to a handler, and doing
+# something with the "stolen" connection.
+#
+# == Description
+#
+# PacketThief is a little Ruby framework for programatically intercepting network
+# traffic. It provides an abstraction around configuring various OS firewalls and
+# for gathering information about the original connection, and it offers several
+# sample handler classes (for use with EventMachine) for intercepting and
+# forwarding traffic. If you want a full fledged security tool for intercepting
+# and analyzing network traffic, check out
+# {Mallory}[http://intrepidusgroup.com/insight/mallory/] instead.
+#
+# PacketThief is currently intended to be run on a computer that should be
+# configured as the gateway for whatever network traffic you wish to intercept.
+# You then use PacketThief to configure your OS firewall and network routing to
+# send specified network traffic to a socket. The socket handling code can then
+# read the data, modify it, send it on to the original destination (although the
+# new connection will originate from the gateway), etc.
+#
+# Currently, PacketThief supports basic redirection using Ipfw (Mac OS X, BSD)
+# and Netfilter (Linux). It also more than likely requires your PacketThief-based
+# script to be run as root in order to modify your system's firewall.
+#
+# == Usage
+#
+# First, you must configure the system that will run PacketThief to be able to
+# intercept network traffic. If that host system has two network interfaces (such
+# as a laptop with ethernet and wifi), then you can turn the system into a router
+# by configure one interface to be an external interface that can communicate
+# with your main network and the Internet, and the other interface can be
+# configured as the gateway for one or more devices/client systems that you would
+# like to test.
+#
+# NATing multiple network interfaces can be easily done in Mac OS X by enabling
+# Internet Sharing in the Sharing System Preference pane, which will also let you
+# configure your wifi to be a wireless access point. For Linux, take a look at
+# the +examples/setup_iptables.sh+ script, or {search the Internet for tutorials
+# on various ways to set up Mallory}[https://bitbucket.org/IntrepidusGroup/mallory/wiki/Home].
+#
+# Basic use:
+#
+#     require 'packetthief'
+#     # redirect tcp traffic destined for port 443 to localhost port 65432:
+#     PacketThief.redirect(:to_ports => 65432).where(:protocol => :tcp, :dest_port => 443).run
+#     at_exit { PacketThief.revert } # Remove our firewall rules when we exit
+#
+# This will set up Firewall/routing rules to redirect packets matching the .where
+# clause to the localhost port specified by the redirect() clause. The
+# Kernel#at_exit handler calls the .revert method which will remove the firewall
+# rules added by PacketThief.
+#
+# You can then capture network traffic in your script by opening a listening
+# socket your +:to_ports+ destination. When you create the socket, set the
+# hostname to a blank string to have it listen on all interfaces -- this winds up
+# being more compatible with different firewalls.
+#
+# Using a TCPServer:
+#
+#     TCPServer.new('', 65432)
+#
+# or (untested):
+#
+#     TCPServer.new(65432)
+#
+# Using EventMachine:
+#
+#     EM.run {
+#         start_server '', 65432, MyHandler
+#     }
+#
+#
+# In your listener code you can recover the original destination by passing in an
+# accepted socket or an EventMachine::Connection-based handler.
+#
+#     PacketThief.original_dest(socket_or_em_connection)
+#
+# PacketThief also provides several EventMachine handlers to help build
+# interceptors. For example, PacketThief::Handlers::TransparentProxy provides a
+# class that allows you to view or mangle arbitrary TCP traffic before passing it
+# on to the original destination. The package also includes several handlers for
+# dealing with SSL-based traffic. Unlike EventMachine's built-in SSL support
+# (#start_tls), PacketThief::Handlers::SSLClient and
+# PacketThief::Handlers::SSLServer give you direct access to the
+# OpenSSL::SSL::SSLContext to configure certificates and callbacks, and
+# PacketThief::Handlers::SSLSmartProxy will connect to the original destination
+# in order to acquire its host certificate, which it then modifies for use with a
+# configured CA. See the documentation and the example directory for more
+# information.
+#
+# == Mac OS X Setup example
+#
+# * Share your wifi over your ethernet. Mac OS X will run natd with your wifi as the lan.
+# * Connect a mobile or wifi device to this wifi.
+# * Run your PacketThief code, and specify `:in_interface => 'en1'` (assuming
+#   your Airport/wifi is on en1) in the .where clause. The specified :to_ports
+#   port should start receiving incoming TCP connections.
+#
+# Note that connections initiated both on the Mac and on any device from the
+# network will hit your socket. In the future, you will be able to narrow down
+# what traffic is caught.
+#
+module PacketThief
+  autoload :RedirectRule, 'packetthief/redirect_rule'
+  autoload :Impl,         'packetthief/impl'
+
+  autoload :Handlers, 'packetthief/handlers'
+  autoload :Logging,  'packetthief/logging'
+  autoload :Util, 'packetthief/util'
+
+  class << self
+    include Logging
+  end
+
+  def self.implementation; @implementation ; end
+
+  def self.implementation=(newimpl)
+    logdebug "Set implementation to: #{newimpl}"
+    if newimpl == nil
+      @implementation = nil
+    elsif newimpl.kind_of? Module
+      @implementation = newimpl
+    else
+      PacketThief::Impl.constants.each do |c|
+        if c.downcase.to_sym == newimpl.downcase.to_sym
+          @implementation = PacketThief::Impl.const_get c
+          return @implementation
+        end
+      end
+      raise AttributeError, "Unknown implementation"
+    end
+  end
+
+  def self.guess_implementation
+    case RUBY_PLATFORM
+    when /linux/
+      Impl::Netfilter
+    when /darwin(10|[0-9]($|[^0]))/ # Mac OS X 10.6 and earlier.
+      Impl::Ipfw
+    when /darwin(11)/ # Mac OS X 10.7
+      Impl::PFRdr
+    else
+      raise "Platform #{RUBY_PLATFORM} not yet supported! If you know your network implementation, call it directly."
+    end
+  end
+
+  # Pass the call on to @implementation, or an OS-specific default, if one is known.
+  def self.method_missing(m, *args, &block)
+    logdebug "method_missing: #{m}", :args => args, :block => block
+    if self.implementation == nil
+      self.implementation = guess_implementation
+    end
+    implementation.logger = @logger if implementation.respond_to? :logger=
+    self.implementation.send(m, *args, &block)
+  end
+
+  # Quietly ignore .revert calls if implementation is nil.
+  def self.revert
+    implementation.revert if implementation
+  end
+
+end