http-security 0.1.0

data/lib/http/security/parsers/public_key_pins.rb

@@ -0,0 +1,43 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class PublicKeyPins < Parser
+        rule :public_key_pins do
+          (
+            public_key_pin_directive >>
+            (semicolon >> public_key_pin_directive).repeat(0)
+          ).as(:directives)
+        end
+        root :public_key_pins
+
+        rule(:public_key_pin_directive) do
+          pin                |
+          max_age            |
+          include_subdomains |
+          report_uri         |
+          strict             |
+          header_extension
+        end
+
+        rule(:pin) do
+          (
+            (stri('pin-') >> hash_algorithm).as(:key) |
+            (stri('pin-') >> unsupported_algorithm).as(:name)
+          ) >> equals >> quoted_string.as(:value)
+        end
+        rule(:hash_algorithm) { stri('sha256') }
+        rule(:unsupported_algorithm) { token }
+
+        directive_rule :include_subdomains, 'includeSubDomains'
+        directive_rule :strict
+
+        rule(:report_uri) do
+          stri("report-uri").as(:key) >> equals >>
+          d_quote >> uri.as(:value) >> d_quote
+        end
+      end
+    end
+  end
+end

data/lib/http/security/parsers/public_key_pins_report_only.rb

@@ -0,0 +1,10 @@
+require 'http/security/parsers/public_key_pins'
+
+module HTTP
+  module Security
+    module Parsers
+      class PublicKeyPinsReportOnly < PublicKeyPins
+      end
+    end
+  end
+end

data/lib/http/security/parsers/set_cookie.rb

@@ -0,0 +1,62 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class SetCookie < Parser
+
+        root :set_cookie
+        rule(:set_cookie) do
+          (cookie >> (str(', ') >> cookie).repeat(0)).as(:list)
+        end
+
+        rule(:cookie) do
+          (
+            cookie_pair.as(:cookie) >> (str('; ') >> cookie_av).repeat(0)
+          ).as(:directives)
+        end
+
+        rule(:cookie_pair) do
+          cookie_name.as(:key) >> str('=') >> cookie_value.as(:value)
+        end
+
+        rule(:cookie_name) { token }
+
+        rule(:cookie_value) do
+          cookie_octet.repeat(0) |
+          str('"') >> cookie_octet.repeat(0) >> str('"')
+        end
+
+        # US-ASCII characters excluding CTLs,
+        # whitespace DQUOTE, comma, semicolon,
+        # and backslash
+        rule(:cookie_octet) do
+          match['\x21\x23-\x2b\x2d-\x3a\x3c-\x5b\x5d-\x7e']
+        end
+
+        rule(:cookie_av) do
+          expires_av | max_age_av | domain_av | path_av | secure_av | httponly_av | extension_av
+        end
+
+        rule(:expires_av) { stri('Expires=') >> sane_cookie_date.as(:expires) }
+        rule(:sane_cookie_date) { http_date }
+        rule(:max_age_av) do
+          stri('Max-Age=') >> (non_zero_digit >> digit.repeat(0)).as(:max_age)
+        end
+
+        rule(:non_zero_digit) { match['\x31-\x39'] } # 1-9
+        rule(:domain_av) { stri('Domain=') >> domain_value.as(:domain) }
+        rule(:domain_value) { host_name }
+
+        rule(:path_av) { stri('Path=') >> path_value.as(:path) }
+        # <any CHAR except CTLs or ";">
+        rule(:path_value) { match['^\x00-\x1f\x7f;'].repeat(0) }
+        rule(:secure_av) { stri('Secure').as(:secure) }
+        rule(:httponly_av) { stri('HttpOnly').as(:http_only) }
+        # <any CHAR except CTLs or ";">
+        rule(:extension_av) { match['^\x00-\x1f\x7f;'].repeat(0) }
+
+      end
+    end
+  end
+end

data/lib/http/security/parsers/strict_transport_security.rb

@@ -0,0 +1,42 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class StrictTransportSecurity < Parser
+        # Strict-Transport-Security
+        # Syntax:
+        #  Strict-Transport-Security = "Strict-Transport-Security" ":"
+        #                              [ directive ]  *( ";" [ directive ] )
+        #
+        #  directive                 = directive-name [ "=" directive-value ]
+        #  directive-name            = token
+        #  directive-value           = token | quoted-string
+        #
+        # where:
+        #
+        # token          = <token, defined in [RFC2616], Section 2.2>
+        # quoted-string  = <quoted-string, defined in [RFC2616], Section 2.2>
+        #
+        # REQUIRED directives: max-age
+        # OPTIONAL directives: includeSubdomains
+        rule(:strict_transport_security) do
+          (
+            (max_age.absent? >> (stp_header_extension >> wsp? >> semicolon >> wsp?)).repeat(0) >>
+            max_age >> (semicolon >> stp_header_extension).repeat(0)
+          ).as(:directives)
+        end
+        root :strict_transport_security
+
+        rule(:stp_header_extension) do
+          include_sub_domains | (
+            token.as(:name) >>
+            (equals >> (token | quoted_string).as(:value)).maybe
+          )
+        end
+
+        directive_rule :include_sub_domains, 'includeSubDomains'
+      end
+    end
+  end
+end

data/lib/http/security/parsers/x_content_type_options.rb

@@ -0,0 +1,19 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class XContentTypeOptions < Parser
+        # X-Content-Type-Options
+        # Syntax:
+        # X-Content-Type-Options: nosniff
+        rule(:x_content_type_options) do
+          no_sniff.as(:directives)
+        end
+        root :x_content_type_options
+
+        directive_rule :no_sniff, 'nosniff'
+      end
+    end
+  end
+end

data/lib/http/security/parsers/x_frame_options.rb

@@ -0,0 +1,47 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class XFrameOptions < Parser
+        # X-Frame-Options
+        # Syntax:
+        # X-Frame-Options = "DENY"
+        #                    / "SAMEORIGIN"
+        #                    / ( "ALLOW-FROM" RWS SERIALIZED-ORIGIN )
+        #
+        #          RWS             = 1*( SP / HTAB )
+        #                        ; required whitespace
+        # Only one can be present
+        rule(:x_frame_options) do
+          (
+            deny        |
+            same_origin |
+            allow_from  |
+            allow_all
+          ).as(:directives)
+        end
+        root :x_frame_options
+
+        directive_rule :deny, 'deny'
+        directive_rule :same_origin, 'sameorigin'
+        directive_rule :allow_all, 'allowall'
+
+        rule(:allow_from) do
+          stri("allow-from").as(:key) >> wsp.repeat(1) >>
+          serialized_origin.as(:value)
+        end
+
+        #
+        # URI
+        #
+        rule(:serialized_origin) do
+          (
+            scheme >> str(":") >> str("//") >> host_name >>
+            (str(":") >> digits.as(:port)).maybe
+          ).as(:uri)
+        end
+      end
+    end
+  end
+end

data/lib/http/security/parsers/x_permitted_cross_domain_policies.rb

@@ -0,0 +1,33 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class XPermittedCrossDomainPolicies < Parser
+        # X-Permitted-Cross-Domain-Policies
+        # Syntax:
+        # X-Permitted-Cross-Domain-Policies = "none"
+        #                    | master-only
+        #                    | by-content-type
+        #                    | by-ftp-filename
+        #                    | all
+        rule(:x_permitted_cross_domain_policies) do
+          (
+            none            |
+            master_only     |
+            by_content_type |
+            by_ftp_filename |
+            all
+          ).as(:directives)
+        end
+        root :x_permitted_cross_domain_policies
+
+        directive_rule :none
+        directive_rule :master_only, 'master-only'
+        directive_rule :by_content_type, 'by-content-type'
+        directive_rule :by_ftp_filename, 'by-ftp-filename'
+        directive_rule :all
+      end
+    end
+  end
+end

data/lib/http/security/parsers/x_xss_protection.rb

@@ -0,0 +1,27 @@
+require 'http/security/parsers/parser'
+
+module HTTP
+  module Security
+    module Parsers
+      class XXSSProtection < Parser
+        # X-XSS-Protection
+        # Syntax:
+        # X-Content-Type-Options: < 1 | 0 >
+        #                         /; mode=block
+        rule(:x_xss_protection) do
+          x_xss_flag >> (semicolon >> x_xss_mode).maybe >> (semicolon >> x_xss_report).maybe
+        end
+        root :x_xss_protection
+
+        rule(:x_xss_flag) { match['01'].as(:boolean).as(:enabled) }
+        rule(:x_xss_mode) do
+          stri("mode") >> equals >> stri("block").as(:mode)
+        end
+
+        rule(:x_xss_report) do
+          stri('report') >> equals >> any.repeat(1).as(:report)
+        end
+      end
+    end
+  end
+end

data/lib/http/security/response.rb

@@ -0,0 +1,323 @@
+require 'http/security/exceptions'
+require 'http/security/parsers'
+require 'http/security/headers'
+require 'http/security/malformed_header'
+
+module HTTP
+  module Security
+    class Response
+
+      include Enumerable
+
+      # The parsed `Cache-Control` header.
+      #
+      # @return [Headers::CacheControl]
+      attr_reader :cache_control
+
+      # The parsed `Content-Security-Policy` header.
+      #
+      # @return [Headers::ContentSecurityPolicy]
+      attr_reader :content_security_policy
+
+      # The parsed `Content-Security-Policy-Report-Only` header.
+      #
+      # @return [Headers::ContentSecurityPolicyReportOnly]
+      attr_reader :content_security_policy_report_only
+
+      # The parsed `Expires` header.
+      #
+      # @return [HTTPDate]
+      attr_reader :expires
+
+      # The parsed `Pragma` header.
+      #
+      # @return [Headers::Pagram]
+      attr_reader :pragma
+
+      # The parsed `Set-Cookie` header.
+      #
+      # @return [Headers::SetCookie]
+      attr_reader :set_cookie
+
+      # The parsed `Strict-Transport-Security` header.
+      #
+      # @return [Headers::StrictTransportSecurity]
+      attr_reader :strict_transport_security
+
+      # The parsed `Public-Key-Pins` header.
+      #
+      # @return [Headers::PublicKeyPin]
+      attr_reader :public_key_pins
+
+      # The parsed `Public-Key-Pins-Report-Only` header.
+      #
+      # @return [Headers::PublicKeyPinsReportOnly]
+      attr_reader :public_key_pins_report_only
+
+      # The parsed `X-Content-Type-Options` header.
+      #
+      # @return [Headers::XContentTypeOptions]
+      attr_reader :x_content_type_options
+      alias content_type_options x_content_type_options
+
+      # The parsed `X-Frame-Options` header.
+      #
+      # @return [Headers::XFrameOptions]
+      attr_reader :x_frame_options
+      alias frame_options x_frame_options
+
+      # The parsed `X-Permitted-Cross-Domain-Policies` header.
+      #
+      # @return [Headers::XPermittedCrossDomainPolicies]
+      attr_reader :x_permitted_cross_domain_policies
+      alias permitted_cross_domain_policies x_permitted_cross_domain_policies
+
+      # The parsed `X-XSS-Protection` header.
+      #
+      # @return [Headers::XXssProtection]
+      attr_reader :x_xss_protection
+      alias xss_protection x_xss_protection
+
+      #
+      # Initializes the response.
+      #
+      # @param [Hash{Symbol => Object}] headers
+      #   The parsed headers.
+      #
+      # @option options [Hash] :cache_control
+      #   The parsed `Cache-Control` header.
+      #
+      # @option options [Hash] :content_security_policy
+      #   The parsed `Content-Security-Policy` header.
+      #
+      # @option options [Hash] :content_security_policy_report_only
+      #   The parsed `Content-Security-Policy-Report-Only` header.
+      #
+      # @option options [Hash] :expires
+      #   The parsed `Expires` header.
+      #
+      # @option options [Hash] :pragma
+      #   The parsed `Pragma` header.
+      #
+      # @option options [Hash] :strict_transport_security
+      #   The parsed `Strict-Transport-Security` header.
+      #
+      # @option options [Array<Hash>] :set_cookie
+      #   The parsed `Set-Cookie` header.
+      #
+      # @option options [Hash] :public_key_pins
+      #   The parsed `Public-Key-Pins` header.
+      #
+      # @option options [Hash] :public_key_pins_report_only
+      #   The parsed `Public-Key-Pins-Report-Only` header.
+      #
+      # @option options [Hash] :x_content_type_options
+      #   The parsed `X-Content-Type-Options` header.
+      #
+      # @option options [Hash] :x_frame_options
+      #   The parsed `X-Frame-Options` header.
+      #
+      # @option options [Hash] :x_permitted_cross_domain_policies
+      #   The parsed `X-Permitted-Cross-Domain-Policies` header.
+      #
+      # @option options [Hash] :x_xss_protection
+      #   The parsed `X-XSS-Protection` header.
+      #
+      # @api semipublic
+      #
+      def initialize(headers={})
+        @cache_control = headers[:cache_control]
+        @content_security_policy = headers[:content_security_policy]
+        @content_security_policy_report_only = headers[:content_security_policy_report_only]
+        @expires = headers[:expires]
+        @pragma = headers[:pragma]
+        @public_key_pins = headers[:public_key_pins]
+        @public_key_pins_report_only = headers[:public_key_pins_report_only]
+        @strict_transport_security = headers[:strict_transport_security]
+        @set_cookie = headers[:set_cookie]
+        @x_content_type_options = headers[:x_content_type_options]
+        @x_frame_options = headers[:x_frame_options]
+        @x_permitted_cross_domain_policies = headers[:x_permitted_cross_domain_policies]
+        @x_xss_protection = headers[:x_xss_protection]
+      end
+
+      # Header names and their corresponding parsers.
+      PARSERS = {
+        'Cache-Control'                       => Parsers::CacheControl,
+        'Content-Security-Policy'             => Parsers::ContentSecurityPolicy,
+        'Content-Security-Policy-Report-Only' => Parsers::ContentSecurityPolicyReportOnly,
+        'Expires'                             => Parsers::Expires,
+        'Pragma'                              => Parsers::Pragma,
+        'Public-Key-Pins'                     => Parsers::PublicKeyPins,
+        'Public-Key-Pins-Report-Only'         => Parsers::PublicKeyPinsReportOnly,
+        'Strict-Transport-Security'           => Parsers::StrictTransportSecurity,
+        'Set-Cookie'                          => Parsers::SetCookie,
+        'X-Content-Type-Options'              => Parsers::XContentTypeOptions,
+        'X-Frame-Options'                     => Parsers::XFrameOptions,
+        'X-Permitted-Cross-Domain-Policies'   => Parsers::XPermittedCrossDomainPolicies,
+        'X-Xss-Protection'                    => Parsers::XXSSProtection
+      }
+
+      # Header names and their corresponding classes
+      HEADERS = {
+        'Cache-Control'                       => Headers::CacheControl,
+        'Content-Security-Policy'             => Headers::ContentSecurityPolicy,
+        'Content-Security-Policy-Report-Only' => Headers::ContentSecurityPolicyReportOnly,
+        'Expires'                             => nil,
+        'Pragma'                              => Headers::Pragma,
+        'Public-Key-Pins'                     => Headers::PublicKeyPins,
+        'Public-Key-Pins-Report-Only'         => Headers::PublicKeyPinsReportOnly,
+        'Strict-Transport-Security'           => Headers::StrictTransportSecurity,
+        'Set-Cookie'                          => Headers::SetCookie,
+        'X-Content-Type-Options'              => Headers::XContentTypeOptions,
+        'X-Frame-Options'                     => Headers::XFrameOptions,
+        'X-Permitted-Cross-Domain-Policies'   => Headers::XPermittedCrossDomainPolicies,
+        'X-Xss-Protection'                    => Headers::XXSSProtection
+      }
+
+      # Header names and their corresponding fields.
+      FIELDS = {
+        'Cache-Control'                       => :cache_control,
+        'Content-Security-Policy'             => :content_security_policy,
+        'Content-Security-Policy-Report-Only' => :content_security_policy_report_only,
+        'Expires'                             => :expires,
+        'Pragma'                              => :pragma,
+        'Public-Key-Pins'                     => :public_key_pins,
+        'Public-Key-Pins-Report-Only'         => :public_key_pins_report_only,
+        'Strict-Transport-Security'           => :strict_transport_security,
+        'Set-Cookie'                          => :set_cookie,
+        'X-Content-Type-Options'              => :x_content_type_options,
+        'X-Frame-Options'                     => :x_frame_options,
+        'X-Permitted-Cross-Domain-Policies'   => :x_permitted_cross_domain_policies,
+        'X-Xss-Protection'                    => :x_xss_protection,
+      }
+
+      #
+      # Parses the HTTP security headers of a HTTP response.
+      #
+      # @param [#[]] response
+      #   An HTTP response object. Must provide access to headers via the `#[]`
+      #   method.
+      #
+      # @return [Response]
+      #   The parsed response.
+      #
+      # @api public
+      #
+      def self.parse(response)
+        fields = {}
+
+        FIELDS.each do |header,field|
+          if (value = response[header])
+            fields[field] = begin
+                              parse_header(header,value)
+                            rescue Parslet::ParseFailed => error
+                              MalformedHeader.new(value,error.cause)
+                            end
+          end
+        end
+
+        return new(fields)
+      end
+
+      #
+      # Parses the HTTP security headers of a HTTP response.
+      #
+      # @param [#[]] response
+      #   An HTTP response object. Must provide access to headers via the `#[]`
+      #   method.
+      #
+      # @return [Response]
+      #
+      # @raise [Parslet::ParseFailed]
+      #   One of the headers was malformed.
+      #
+      # @api public
+      #
+      def self.parse!(response)
+        fields = {}
+
+        FIELDS.each do |name,field|
+          if (value = response[name])
+            fields[field] = parse_header(name,value)
+          end
+        end
+
+        return new(fields)
+      end
+
+      #
+      # Parses an individual header.
+      #
+      # @param [String] name
+      #   The header name.
+      #
+      # @param [String] value
+      #   The raw value of the header.
+      #
+      # @return [Hash]
+      #   The parsed header data.
+      #
+      # @raise [InvalidHeader]
+      #   The header was malformed.
+      #
+      def self.parse_header(name,value)
+        parser = PARSERS.fetch(name)
+        value  = begin
+                   parser.parse(value)
+                 rescue Parslet::ParseFailed => error
+                   raise(InvalidHeader.new(error.message,error.cause))
+                 end
+
+        if (header = HEADERS[name])
+          header.new(value)
+        else
+          value
+        end
+      end
+
+      #
+      # Accesses an arbitrary security header.
+      #
+      # @param [String] header
+      #   The canonical header name.
+      #
+      # @return [Object, nil]
+      #   The parsed header value.
+      #   
+      def [](header)
+        field = FIELDS.fetch(header)
+
+        return instance_variable_get("@#{field}")
+      end
+
+      #
+      # Enumerates over the parsed security header values.
+      #
+      # @yield [name, value]
+      #   The given block will be passed each header name and parsed value.
+      #
+      # @yieldparam [String] name
+      #   The canonical header name.
+      #
+      # @yieldparam [Object] value
+      #   A header class from {Headers}.
+      #
+      # @return [Enumerator]
+      #   If no block was given, an enumerator will be returned.
+      #
+      def each
+        return enum_for(__method__) unless block_given?
+
+        FIELDS.each do |header,field|
+          if (value = self[header])
+            yield header, value
+          end
+        end
+
+        return self
+      end
+
+    end
+  end
+end