castanet 0.0.2 → 1.0.0

data/History.md

@@ -1,3 +1,14 @@
+1.0.0 (2011-02-18)
+==================
+
+Backwards-incompatible changes
+------------------------------
+
+- `Castanet::Client#https_disabled` has changed to
+  {Castanet::Client#https_required}, and mixed HTTP/HTTPS communication is now
+  possible.  See the documentation of {Castanet::Client} for more information.
+- {Castanet::ProxyTicket#reify!} no longer returns `self`.
+
 0.0.2 (2011-02-14)
 ==================
 

data/lib/castanet/client.rb

@@ -39,32 +39,30 @@ module Castanet
   # 1. be accessible over HTTPS and
   # 2. present an SSL certificate that
   #     1. is valid and
-  #     2. has a canonical name that matches that of the proxy callback service.
+  #     2. has a canonical name that matches that of the proxy callback
+  #     service.
   #
-  # Secure channels are not required for any other part of the CAS protocol,
-  # but we still recommend using HTTPS for all communication involving any
-  # permutation of interactions between the CAS server, the user, and the
-  # application.
+  # Secure channels are not required for any other part of the CAS protocol.
   #
-  # Because of this ambiguity in the CAS protocol -- and because unencrypted
-  # transmission can be useful in isolated development environments -- Castanet
-  # will permit non-HTTPS communication with CAS servers.  However, you must
-  # explicitly declare your intent in the class using this client by defining
-  # {#https_disabled} equal to `true`:
+  # By default, Castanet requires HTTPS for all communication with the CAS
+  # server or CAS proxy callback, and will raise a `RuntimeError` when
+  # non-HTTPS communication is attempted.
+  #
+  # However, because of the above ambiguity in the CAS protocol -- and because
+  # unencrypted transmission can be useful in isolated development environments
+  # -- Castanet will permit non-HTTPS communication with CAS servers.  However,
+  # you must explicitly declare your intent in the class using this client by
+  # defining {#https_required} equal to `false`:
   #
   #     class InsecureClient
   #       include Castanet::Client
   #
-  #       def https_disabled
-  #         true
+  #       def https_required
+  #         false
   #       end
   #     end
   #
-  # Also keep in mind that future revisions of Castanet may remove this option.
-  #
   # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol, section 2.5.4
-  # @see http://www.daemonology.net/blog/2009-09-04-complexity-is-insecurity.html
-  #   "Complexity is insecurity" by Colin Percival
   #
   # Examples
   # ========
@@ -102,16 +100,15 @@ module Castanet
   #
   #     ticket.ok? # => true or false
   #
-  #
   # @see http://www.jasig.org/cas/protocol CAS 2.0 protocol
   module Client
     ##
-    # Whether or not to disable HTTPS for CAS server communication.  Defaults
-    # to false.
+    # Whether or not to require HTTPS for CAS server communication.  Defaults
+    # to true.
     #
-    # @return [false]
-    def https_disabled
-      false
+    # @return [true]
+    def https_required
+      true
     end
 
     ##
@@ -159,7 +156,7 @@ module Castanet
     # @return [ServiceTicket]
     def service_ticket(ticket, service)
       ServiceTicket.new(ticket, service).tap do |st|
-        st.https_disabled = https_disabled
+        st.https_required = https_required
         st.proxy_callback_url = proxy_callback_url
         st.proxy_retrieval_url = proxy_retrieval_url
         st.service_validate_url = service_validate_url
@@ -180,10 +177,12 @@ module Castanet
     # @return [ProxyTicket] the issued proxy ticket
     def issue_proxy_ticket(pgt, service)
       ProxyTicket.new(nil, pgt, service).tap do |pt|
-        pt.https_disabled = https_disabled
+        pt.https_required = https_required
         pt.proxy_url = proxy_url
         pt.proxy_validate_url = proxy_validate_url
-      end.reify!
+
+        pt.reify!
+      end
     end
 
     ##
@@ -197,7 +196,7 @@ module Castanet
     # @return [ProxyTicket]
     def proxy_ticket(ticket, service)
       ProxyTicket.new(ticket.to_s, nil, service).tap do |pt|
-        pt.https_disabled = https_disabled
+        pt.https_required = https_required
         pt.proxy_callback_url = proxy_callback_url
         pt.proxy_retrieval_url = proxy_retrieval_url
         pt.proxy_url = proxy_url

data/lib/castanet/proxy_ticket.rb

@@ -83,24 +83,20 @@ module Castanet
     # run multiple times, but each invocation will overwrite {#ticket} with a
     # new ticket.
     #
-    # This method is automatically called by {Client#proxy_ticket}, and as such
-    # should never need to be called by users of Castanet; however, in the
-    # interest of program organization, the method is public and located here.
-    # Also, if you're managing `ProxyTicket` instances manually for some reason,
-    # you may find this method useful.
+    # This method is automatically called by {Client#issue_proxy_ticket}, and
+    # as such should never need to be called by users of Castanet; however, in
+    # the interest of program organization, the method is public and located
+    # here.  Also, if you're managing `ProxyTicket` instances manually for some
+    # reason, you may find this method useful.
     #
     # @raise [ProxyTicketError] if a proxy ticket cannot be issued
-    # @return [ProxyTicket] self
+    # @return void
     def reify!
       uri = URI.parse(proxy_url).tap do |u|
         u.query = grant_parameters
       end
 
-      http = Net::HTTP.new(uri.host, uri.port).tap do |h|
-        h.use_ssl = !https_disabled
-      end
-
-      http.start do |h|
+      net_http(uri).start do |h|
         cas_response = h.get(uri.to_s)
 
         self.proxy_response = parsed_proxy_response(cas_response.body)
@@ -108,8 +104,6 @@ module Castanet
         unless issued?
           raise ProxyTicketError, "A proxy ticket could not be issued.  Code: <#{failure_code}>, reason: <#{failure_reason}>."
         end
-
-        self
       end
     end
 

data/lib/castanet/service_ticket.rb

@@ -10,7 +10,7 @@ module Castanet
     include QueryBuilding
 
     ##
-    # Set this to `true` to _not_ use HTTPS for CAS server communication.
+    # Set this to `false` to allow plain HTTP for CAS server communication.
     #
     # In almost all cases where CAS is used, there is no good reason to avoid
     # HTTPS.  However, if you
@@ -23,7 +23,7 @@ module Castanet
     # This is usually set by {Castanet::Client}.
     #
     # @return [Boolean]
-    attr_accessor :https_disabled
+    attr_accessor :https_required
 
     ##
     # The proxy callback URL to use for service validation.
@@ -75,6 +75,7 @@ module Castanet
     attr_accessor :pgt
 
     def initialize(ticket, service)
+      @https_required = true
       @service = service
       @ticket = ticket
     end
@@ -112,11 +113,7 @@ module Castanet
         u.query = validation_parameters
       end
 
-      http = Net::HTTP.new(uri.host, uri.port).tap do |h|
-        h.use_ssl = !https_disabled
-      end
-
-      http.start do |h|
+      net_http(uri).start do |h|
         cas_response = h.get(uri.to_s)
 
         self.response = parsed_ticket_validate_response(cas_response.body)
@@ -143,11 +140,7 @@ module Castanet
         u.query = query(['pgtIou', pgt_iou])
       end
 
-      http = Net::HTTP.new(uri.host, uri.port).tap do |h|
-        h.use_ssl = !https_disabled
-      end
-
-      http.start do |h|
+      net_http(uri).start do |h|
         self.pgt = h.get(uri.to_s).body
       end
     end
@@ -162,6 +155,17 @@ module Castanet
       service_validate_url
     end
 
+    ##
+    # Creates a new {Net::HTTP} instance which can be used to connect
+    # to the designated URI.
+    #
+    # @return [Net::HTTP]
+    def net_http(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |h|
+        h.use_ssl = use_ssl?(uri.scheme)
+      end
+    end
+
     private
 
     ##
@@ -176,5 +180,23 @@ module Castanet
             ['service', service],
             ['pgtUrl',  proxy_callback_url])
     end
+
+    ##
+    # Determines whether to use SSL based on the the given URI scheme and the
+    # {#https_required} attribute.
+    #
+    # @raise if the scheme is `http` but {#https_required} is true
+    # @return [Boolean]
+    def use_ssl?(scheme)
+      case scheme.downcase
+      when 'https'
+        true
+      when 'http'
+        raise 'Castanet requires SSL for all communication' if https_required
+        false
+      else
+        fail "Unexpected URI scheme #{scheme.inspect}"
+      end
+    end
   end
 end

data/lib/castanet/version.rb

@@ -1,3 +1,3 @@
 module Castanet
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

metadata

@@ -3,10 +3,10 @@ name: castanet
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
+  - 1
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors: 
 - David Yip
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-14 00:00:00 -06:00
+date: 2011-02-18 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -136,18 +136,18 @@ files:
 - README.md
 - History.md
 - LICENSE
-- lib/castanet/service_ticket.rb
-- lib/castanet/responses.rb
-- lib/castanet/responses/proxy.rl
+- lib/castanet/client.rb
+- lib/castanet/proxy_ticket.rb
+- lib/castanet/proxy_ticket_error.rb
+- lib/castanet/query_building.rb
+- lib/castanet/responses/common.rl
 - lib/castanet/responses/proxy.rb
+- lib/castanet/responses/proxy.rl
 - lib/castanet/responses/ticket_validate.rb
-- lib/castanet/responses/common.rl
 - lib/castanet/responses/ticket_validate.rl
-- lib/castanet/proxy_ticket_error.rb
-- lib/castanet/client.rb
+- lib/castanet/responses.rb
+- lib/castanet/service_ticket.rb
 - lib/castanet/version.rb
-- lib/castanet/proxy_ticket.rb
-- lib/castanet/query_building.rb
 - lib/castanet.rb
 has_rdoc: true
 homepage: ""