tlspretense 0.6.2 → 0.7.0

data/lib/tlspretense/cert_maker/certificate_factory.rb

@@ -59,6 +59,7 @@ module CertMaker
       # Prep for extensions
       ef = OpenSSL::X509::ExtensionFactory.new
       ef.subject_certificate = nc
+      san_ef = SubjectAltNameFactory.new
 
       self.ca = args.indifferent_fetch(:ca,self.ca)
       # Issuer handling
@@ -85,7 +86,16 @@ module CertMaker
 
       # Add the extensions
       exts.each do |ext|
-        nc.add_extension(ef.create_ext_from_string(ext))
+        # hack to allow null bytes in subjectAltName DNS entries.
+        if ext.kind_of? String
+          if ext.strip.index('subjectAltName') == 0
+            nc.add_extension(san_ef.create_san_ext(ext))
+          else
+            nc.add_extension(ef.create_ext_from_string(ext))
+          end
+        else # hash
+          nc.add_extension(OpenSSL::X509::Extension.new(ext['oid'],ext['value'],ext['critical']))
+        end
       end
 
       # Look up the signing algorithm. If it is set to a symbol or string,

data/lib/tlspretense/cert_maker/certificate_suite_generator.rb

@@ -81,12 +81,26 @@ module CertMaker
         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)
+      certinfo['subject'] = replace_tokens(certinfo['subject'])
       if certinfo.has_key? 'extensions'
-        certinfo['extensions'] = certinfo['extensions'].map { |ext| ext.gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname) }
+        certinfo['extensions'] = certinfo['extensions'].map do |ext|
+          if ext.kind_of? String
+            replace_tokens ext
+          else
+            ext['value'] = replace_tokens(ext['value'])
+            ext
+          end
+        end
       end
       if certinfo.has_key? 'addextensions'
-        certinfo['addextensions'] = certinfo['addextensions'].map { |ext| ext.gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname) }
+        certinfo['addextensions'] = certinfo['addextensions'].map do |ext|
+          if ext.kind_of? String
+            replace_tokens(ext)
+          else
+            ext['value'] = replace_tokens(ext['value'])
+            ext
+          end
+        end
       end
       # doctor the serial number.
       if @config.has_key? 'missing_serial_generation'
@@ -116,6 +130,10 @@ module CertMaker
       end
     end
 
+    def replace_tokens(str)
+        str.gsub(/%HOSTNAME%/, @defaulthostname).gsub(/%PARENTHOSTNAME%/, @parenthostname)
+    end
+
   end
 end
 end

data/lib/tlspretense/cert_maker/subject_alt_name_factory.rb

@@ -0,0 +1,115 @@
+module TLSPretense
+  module CertMaker
+    # SubjectAltName, in ASN1, is a sequence comprised of a tag identifying the
+    # extension type (subjectAltName, which has objectid tag of 6), and then an
+    # octect string that contains an ASN1 encoded sequence of alternative
+    # names. Each alternative name is then an ASN1Data with a context-specific
+    # tag id. DNS has a tag id of 2, and the string (an IA5String) is just an
+    # ascii string (meaning we can have null bytes!)
+    #
+    #     pp asn1
+    #     #<OpenSSL::ASN1::Sequence:0x00000100ac2ca8
+    #      @infinite_length=false,
+    #      @tag=16,
+    #      @tag_class=:UNIVERSAL,
+    #      @tagging=nil,
+    #      @value=
+    #       [#<OpenSSL::ASN1::ObjectId:0x00000100ac2d20
+    #         @infinite_length=false,
+    #         @tag=6,
+    #         @tag_class=:UNIVERSAL,
+    #         @tagging=nil,
+    #         @value="subjectAltName">,
+    #        #<OpenSSL::ASN1::OctetString:0x00000100ac2cd0
+    #         @infinite_length=false,
+    #         @tag=4,
+    #         @tag_class=:UNIVERSAL,
+    #         @tagging=nil,
+    #         @value="0\x1E\x82\x1Cwww.isecpartners.com\x00foo.com">]>
+    #
+    #     pp OpenSSL::ASN1.decode(asn1.value[1].value)
+    #     #<OpenSSL::ASN1::Sequence:0x00000100ba16d8
+    #      @infinite_length=false,
+    #      @tag=16,
+    #      @tag_class=:UNIVERSAL,
+    #      @tagging=nil,
+    #      @value=
+    #       [#<OpenSSL::ASN1::ASN1Data:0x00000100ba1700
+    #         @infinite_length=false,
+    #         @tag=2,
+    #         @tag_class=:CONTEXT_SPECIFIC,
+    #         @value="www.isecpartners.com\x00foo.com">]>
+    class SubjectAltNameFactory
+      # Creates a subjectAltName extension using a specified dnsname.
+      #
+      # The purpose here is to bypass the normal OpenSSL subjectAltName
+      # constructors because they treat input as a C string at some point,
+      # losing everything after a null byte.
+      def initialize
+        # Lazy-make an existing subjectAltName extension to start from.
+        @ef = OpenSSL::X509::ExtensionFactory.new
+      end
+
+      def create_san_with_dns(dnsname)
+        ext = @ef.create_ext_from_string('subjectAltName=DNS:placeholder')
+        ext_asn1 = OpenSSL::ASN1.decode(ext.to_der)
+        san_list_der = ext_asn1.value[1].value
+        san_list_asn1 = OpenSSL::ASN1.decode(san_list_der)
+
+        san_list_asn1.value[0].value = dnsname
+
+        ext_asn1.value[1].value = san_list_asn1.to_der
+
+        OpenSSL::X509::Extension.new ext_asn1
+      end
+
+      # Generates a subjectAltName extension, but with improved null byte
+      # support.
+      #
+      # Desc should look like normal OpenSSL extension description. Eg:
+      #
+      #     subjectAltName=DNS:foo.com, DNS:bar.com
+      #
+      # However, if a DNS entry contains a null byte, it doctors the extension
+      # to properly include the null byte (Either Ruby's openssl library or
+      # something in OpenSSL itself uses a C string at some point, dropping the
+      # null byte).
+      def create_san_ext(desc)
+        # Remove any DNSName entries with null bytes.
+        nulldomains = {}
+        # $1 is the domain
+        # $2 is the comma after
+        desc = desc.gsub(/DNS:\s*([^\s,]*\0[^\s,]*)\s*(,?)/) do |match|
+          nulldomains[$1.hash] = $1
+
+          "DNS:placeholder#{$1.hash.to_s}#{$2}"
+        end
+        ext = @ef.create_ext_from_string(desc)
+
+        # Find the placeholder entries for the removed entries and doctor them.
+        nulldomains.each_pair do |domainhash,domainwithnull|
+          ext = replace_in_san(ext,"placeholder#{domainhash.to_s}",domainwithnull)
+        end
+        ext
+      end
+
+      def replace_in_san(ext, olddns, newdns)
+        ext_asn1 = OpenSSL::ASN1.decode(ext.to_der)
+        san_list_der = ext_asn1.value[1].value
+        san_list_asn1 = OpenSSL::ASN1.decode(san_list_der)
+
+        san_list_asn1.value.map do |entry|
+          if entry.tag == 2 and entry.value == olddns
+            entry.value = newdns
+          end
+          entry
+        end
+
+        ext_asn1.value[1].value = san_list_asn1.to_der
+
+        OpenSSL::X509::Extension.new ext_asn1
+      end
+
+    end
+  end
+end

data/lib/tlspretense/ext_compat/openssl_pkey_read.rb

@@ -0,0 +1,38 @@
+
+module TLSPretense
+  module ExtCompat
+    # In Ruby versions before 1.9.3, OpenSSL::PKey.read does not exist. It is
+    # not something that can be easily back-ported (it is written in C with
+    # OpenSSL functions that are not directly exposed through the Ruby
+    # library), so this module provides a partial reimplementation suitable for
+    # TLSPretense's purposes.
+    #
+    # It blindly tries each class until one works. If none work, it finally
+    # gives up. The error message won't ever be particularly helpful.
+    module OpenSSLPKeyRead
+      def read(data, passwd=nil)
+        begin
+          OpenSSL::PKey::RSA.new(data, passwd)
+        rescue OpenSSL::PKey::RSAError => e
+          begin
+            OpenSSL::PKey::DSA.new(data, passwd)
+          rescue OpenSSL::PKey::DSAError
+            begin
+              OpenSSL::PKey::EC.new(data, passwd)
+            rescue OpenSSL::PKey::ECError
+              raise "Failed to read a private key. Is the password correct?"
+            end
+          end
+        end
+      end
+
+      def self.check_and_apply_patch
+        unless ::OpenSSL::PKey.respond_to? :read
+          $stderr.puts "Warning: OpenSSL::PKey does not respond to :read (added in Ruby 1.9.3). Monkeypatching it to provide enough functionality for TLSPretense."
+          ::OpenSSL::PKey.extend(self)
+        end
+      end
+
+    end
+  end
+end

data/lib/tlspretense/skel/config.yml

@@ -192,13 +192,27 @@ certs:
     addextensions:
     - "subjectAltName=DNS:www.foo.com"
 
-  # This fails to generate as desired. the null byte truncates the
-  # subjectAltName somewhere within OpenSSL. We need to manually construct the
-  # ASN1 encoding ourselves.
-#  nullinsubjectaltname: &nullinsubjectaltname
-#    <<: *subjectaltnameonly
-#    addextensions:
-#    - "subjectAltName=DNS:%HOSTNAME%\x00.foo.com, DNS:another.com"
+  # The nullinsubjectaltname certificate will generate as intended with
+  # TLSPretense 0.7.0 and later. TLSPretense partially reconstructs
+  # subjectAltName extensions that contain a null byte in a DNSName. Note that
+  # the OpenSSL command line display of the certificate will truncate a
+  # subjectAltName DNSName entry at the null byte, failing to display the full
+  # entry. Eg:
+  #
+  #     $ openssl x509 -in certs/nullinsubjectaltnamecert.pem -noout -text
+  #     ...
+  #                 X509v3 Subject Alternative Name:
+  #                     DNS:www.isecpartners.com, DNS:another.com
+  #     ...
+  #
+  # when the first entry is actually "www.isecpartners.com\0.foo.com". However,
+  # the full DNSName can be verified by examining the bytes of the DER encoding
+  # of the certificate, or by parsing the extension and carefully examining the
+  # ASN1 tree.
+  nullinsubjectaltname: &nullinsubjectaltname
+    <<: *subjectaltnameonly
+    addextensions:
+    - "subjectAltName=DNS:%HOSTNAME%\x00.foo.com, DNS:another.com"
 
   parentinsubjectaltname: &parentinsubjectaltname
     <<: *subjectaltnameonly
@@ -315,6 +329,19 @@ certs:
     <<: *baseline
     issuer: expiredca
 
+  unknownnoncriticalextension:
+    <<: *baseline
+    addextensions:
+    - oid: 1.2.3.4.5.6.7.8.9.10
+      value: ' ' # must have something
+      critical: false
+
+  unknowncriticalextension:
+    <<: *baseline
+    addextensions:
+    - oid: 1.2.3.4.5.6.7.8.9.10
+      value: ' ' # must have something
+      critical: true
 
 tests:
 # baseline
@@ -324,6 +351,9 @@ tests:
   - baseline
   - goodca
   expected_result: connected
+  description: |
+    A "good" certificate and chain that should always pass. If this test fails,
+    then your client probably does not trust the goodca CA certificate.
 
 # cname tests
 - alias: wrongcname
@@ -332,6 +362,9 @@ tests:
   - wrongcname
   - goodca
   expected_result: rejected
+  description: |
+    If the supplied CNAME does not match the expected hostname (and there is no
+    subjectAltName), then the certificate is for the wrong host.
 
 # cname tests
 - alias: parentcname
@@ -340,6 +373,9 @@ tests:
   - parentcname
   - goodca
   expected_result: rejected
+  description: |
+    Sanity check for extremely lenient hostname verification. A common name on
+    a certificate should match all of a hostname, not just the parent domain.
 
 - alias: nullincname
   name: Null character in CNAME
@@ -347,21 +383,33 @@ tests:
   - nullincname
   - goodca
   expected_result: rejected
+  description: |
+    If the common name contains a null character (often represented
+    in printable form as "\0" or "\x00" for single-byte text encodings), then
+    an attacker might be able to bypass hostname validation that uses C
+    strings. For example, a common name of "example.com\x00.evil.com", when
+    interpreted as a C string, would match "example.com".
 
 # subjectAltName tests
 - alias: happysubjectaltname
-  name: Hostname is a dnsName in subjectAltName and in subject
+  name: Hostname is a dNSName in subjectAltName and in subject
   certchain:
   - baselinesubjectaltname
   - goodca
   expected_result: connected
+  description: |
+  Test to ensure that the client does not behave badly if the hostname is in
+  both the common name and in a dNSName subjectAltNAme entry.
 
 - alias: happysubjectaltnameonly
-  name: hostname only a dnsName subjectAltName
+  name: hostname only a dNSName subjectAltName
   certchain:
   - subjectaltnameonly
   - goodca
   expected_result: connected
+  description: |
+    Test to ensure that the client supports a matching dNSName entry in the
+    subjectAltName when the hostname is not represented in the common name.
 
 - alias: wrongsubjectaltnamewrongsubject
   name: hostname in neither subjectAltName nor subject
@@ -369,6 +417,11 @@ tests:
   - wrongsubjectaltnamewrongsubject
   - goodca
   expected_result: rejected
+  description: |
+    If the hostname is not in either a subjectAltName or the common name, then
+    the certificate does not match the hostname. Failure to reject means an
+    attacker may be able to use a certificate for a different hostname to spoof
+    users.
 
 - alias: wrongsubjectaltnamerightsubject
   name: hostname in subject but not in subjectAltName
@@ -376,20 +429,35 @@ tests:
   - wrongsubjectaltnamerightsubject
   - goodca
   expected_result: rejected
+  description: |
+    If a certificate has a subjectAltName extension, then the client should not
+    check the common name. The common name does not have to be a hostname, and
+    there might be circumstance where a CA allows an arbitrary common name that
+    happens to match someone elses hostname.
+
+- alias: nullinsubjectaltname
+  name: "null byte in subjectAltName"
+  certchain:
+  - nullinsubjectaltname
+  - goodca
+  expected_result: rejected
+  description: |
+    dNSName entries in the subjectAltName extension are susceptible to null
+    characters, just like the common name. If a dNSName entry contains a null
+    character (often represented in printable form as "\0" or "\x00" for
+    single-byte text encodings), then an attacker might be able to bypass
+    hostname validation that uses C strings. For example, a dNSName of
+    "example.com\x00.evil.com", when interpreted as a C string, would match
+    "example.com".
 
-#- alias: nullinsubjectaltname
-#  name: "null byte in subjectAltName"
-#  certchain:
-#  - nullinsubjectaltname
-#  - goodca
-#  expected_result: rejected
-#
 - alias: parentinsubjectaltname
   name: "parent domain in subjectAltName"
   certchain:
   - parentinsubjectaltname
   - goodca
   expected_result: rejected
+  description: |
+    A dNSName entry should match all of a hostname, not just the parent domain.
 
 # key usage
 - alias: wrongextendedkeyusage
@@ -398,6 +466,17 @@ tests:
   - wrongextendedkeyusage
   - goodca
   expected_result: rejected
+  description: |
+    If a certificate has an extendedKeyUsage extension, then a client should
+    ensure that the certificate has the right usage flags set. TLSPretense
+    assumes the client is connecting to a server (as opposed to validating the
+    signature on an SMIME-signed email message, code signature, or some other
+    operation), so a certificate that has an extendedKeyUsage that lacks the
+    serverAuth bit should be rejected.
+    
+    To exploit, an attacker would need to have a valid certificate for the
+    targeted domain, except that its extendedKeyUsage states it is for some
+    other purpose, such as code signing, non-repudiation, or OCSP signing.
 
 - alias: rightextendedkeyusagecrit
   name: extendedKeyUsage lacks serverAuth
@@ -405,6 +484,9 @@ tests:
   - rightextendedkeyusagecrit
   - goodca
   expected_result: connected
+  description: |
+    Happy test that essentially duplicates the baseline test, but for
+    comparison to the other extendedKeyUsage tests.
 
 #####################
 # This one fails against Java/Android's standard SSL client code.
@@ -414,6 +496,12 @@ tests:
   - wrongextendedkeyusagecrit
   - goodca
   expected_result: rejected
+  description: |
+    If the extendedKeyUsage extension is marked critical, and it has the wrong
+    flags set, then the client should reject this certificate. This particular
+    test is here to help determine whether a client that failed the
+    wrongextendedkeyusage test also properly honors the critical flag.
+
 #####################
 
 # cert chain issues
@@ -422,6 +510,10 @@ tests:
   certchain:
   - selfsigned
   expected_result: rejected
+  description: |
+    Anyone can create an arbitrary self-signed certificate. Without some
+    non-PKI mechanism for verifying whether the certificate is valid or not,
+    self-signed certificates cannot be trusted at all.
 
 - alias: unknownca
   name: Signed by an untrusted CA
@@ -429,6 +521,9 @@ tests:
   - unknowncacert
   - unknownca
   expected_result: rejected
+  description: |
+    A certificate signed by a CA that the client is unaware of is as dangerous
+    as a self-signed certificate -- anyone can craft such a certificate chain.
 
 - alias: differentkeyca
   name: Signed by an untrusted CA (provided in the chain) with the same name but a different key
@@ -436,6 +531,12 @@ tests:
   - signedbydifferentkey
   - cawithdifferentkey
   expected_result: rejected
+  description: |
+    When validating the certificate chain, it is critical for a client to
+    ensure that the CA is valid. An attacker could craft a CA that is identical
+    in every way to a CA that the client trusts but that uses a different
+    key-pair. This would easily allow an attacker to spoof a legitimate
+    certificate.
 
 - alias: badsignature
   name: Bad signature
@@ -443,6 +544,9 @@ tests:
   - badsignature
   - goodca
   expected_result: rejected
+  description: |
+    If the signature on the leaf certificate does not match the public key of
+    the CA that signed it, then an attacker could easily spoof the site.
 
 - alias: cafalseintermediate
   name: "Intermediate certificate where BasicConstraints sets CA:FALSE"
@@ -451,6 +555,13 @@ tests:
   - cafalseintermediate
   - goodca
   expected_result: rejected
+  description: |
+    While verifying the certificate chain, the client should ensure that all
+    certificates that attest to the identity of the leaf certificate are
+    actually CAs themselves (including all intermediate certificates).
+    Otherwise, an attacker could take a legitimate leaf node and use it to sign
+    a fake certificate. The verificate of the certificate chain passes because
+    the client fails to check the BasicConstraints.
 
 - alias: nobcintermediate
   name: Intermediate certificate lacks BasicConstraints
@@ -459,6 +570,10 @@ tests:
   - nobcintermediate
   - goodca
   expected_result: rejected
+  description: |
+    An intermediate certificate that lacks the BasicConstraints extension
+    should be treated as if its constriants stated that it was not a CA
+    (CA:FALSE).
 
 - alias: badsigonintermediate
   name: Intermediate certificate has bad signature from CA
@@ -467,6 +582,10 @@ tests:
   - badsigintermediate
   - goodca
   expected_result: rejected
+  description: |
+    If the signature on an intermediate certificate does not match the public
+    key of the CA that signed it, then an attacker could easily spoof the leaf
+    certificate.
 
 - alias: signedwithmd5
   name: Certificate signed with MD5
@@ -474,6 +593,12 @@ tests:
   - signedwithmd5
   - goodca
   expected_result: rejected
+  description: |
+    MD5 is a hash signing algorithm with known weaknesses. Researchers have
+    been able to create signature collisions, which means an attacker might be
+    able to create a certificate whose MD5 hash matches that of a certificate
+    with a valid signature. However, many existing certificates are signed with
+    MD5, although new leaf certificates should not be signed this way.
 
 - alias: signedwithmd4
   name: Certificate signed with MD4
@@ -481,6 +606,8 @@ tests:
   - signedwithmd4
   - goodca
   expected_result: rejected
+  description: |
+    MD5 is a deprecated hash signing algorithm. It should never be used.
 
 ## Need OpenSSL built with MD2 support
 #- alias: signedwithmd2
@@ -489,6 +616,8 @@ tests:
 #  - signedwithmd2
 #  - goodca
 #  expected_result: rejected
+#  description: |
+#    MD2 is an even older hash signing algorithm.
 
 - alias: expiredcert
   name: Certificate that has expired
@@ -496,6 +625,12 @@ tests:
   - expiredcert
   - goodca
   expected_result: rejected
+  description: |
+    An expired certificate should not be trusted by a client. CAs mandate
+    expiration dates in order to limit how long a certificate is valid for.
+    This allows them to charge money to re-issue a certificate, but it also
+    allows them change certificate requirements over time and eventually phase
+    out old certificates.
 
 - alias: notyetvalidcert
   name: Certificate that is valid in the future
@@ -503,6 +638,9 @@ tests:
   - notyetvalidcert
   - goodca
   expected_result: rejected
+  description: |
+    A certificate that is not yet valid is suspicious. Either the client's
+    clock is running slow, or something else odd is going on.'
 
 - alias: expiredintermediate
   name: Certificate signed by an intermediate that has expired
@@ -511,6 +649,12 @@ tests:
   - expiredintermediate
   - goodca
   expected_result: rejected
+  description: |
+    An expired certificate, including expired intermediate certificates, should
+    not be trusted by a client. CAs mandate expiration dates in order to limit
+    how long a certificate is valid for. This allows them to charge money to
+    re-issue a certificate, but it also allows them change certificate
+    requirements over time and eventually phase out old certificates.
 
 # This requires installing the expired CA that is also installed into the
 # client's trusted root store.
@@ -520,4 +664,37 @@ tests:
 #  - signedbyexpiredca
 #  - expiredca
 #  expected_result: rejected
-
+#  description: |
+#    An expired CA should not be trusted. If the CA has been compromised since
+#    its expiration (eg, the company who created it went out of business and its
+#    assets were sold, including drives that contained the CA's private key),
+#    then an attacker could use it to create arbitrary certificates that would
+#    work against clients that still trust the CA.'
+
+- alias: unknownnoncriticalextension
+  name: Certificate contains a non-critical extension that the client does not understand
+  certchain:
+  - unknownnoncriticalextension
+  - goodca
+  expected_result: connected
+  description: |
+    In general, a well behaved client should ignore non-critical extensions
+    that it does not know how to validate. This test exepcts clients to ignore
+    such an extension, although rejecting an arbitrary non-critical extension
+    does not create a security issue (although the client may not be very
+    usable in practice).
+
+- alias: unknowncriticalextension
+  name: Certificate contains a critical extension that the client does not understand
+  certchain:
+  - unknowncriticalextension
+  - goodca
+  expected_result: rejected
+  description: |
+    A well behaved client must reject the certificate if the certificate has an
+    extension marked critical that it does not know how to validate. Many
+    extensions on legitimately signed certificates are marked as critical to
+    force clients to verify them. Being unable to verify a particular critical
+    extension could mean that someone could use some other nearly identical
+    certificate (aside from the details of the unhandled critical extension) in
+    place of the correct one.