winrm 0.0.6 → 1.0.0rc1

data/README

@@ -7,47 +7,68 @@ not limitted to, running batch scripts, powershell scripts and fetching WMI
 variables.  For more information on WinRM, please visit Microsoft's WinRM
 site: http://msdn.microsoft.com/en-us/library/aa384426(v=VS.85).aspx
 
-* This version does not currently support encryption of messages via
-  Kerberos so it is highly recommended to use SSL when configuring WinRM.
-  'winrm quickconfig -transport:https'
-
-
 My Info: 
 BLOG:  http://distributed-frostbite.blogspot.com/
 Add me in LinkedIn:  http://www.linkedin.com/in/danwanek
 Find me on irc.freenode.net in #ruby-lang (zenChild)
 
 --------------------------------------------------------------------------
+Version 1.0.0rc1
+
+This is a release candidate of the new version 1 code for Ruby WinRM. It
+is almost a complete re-write from the previous version to support some
+of the following major feature additions:
+
+1. GSSAPI support:  This is the default way that Windows authenticates and
+   secures WinRM messages. In order for this to work the computer you are
+   connecting to must be a part of an Active Directory domain and you must
+   have local credentials via kinit. GSSAPI support is dependent on the
+   gssapi gem which only supports the MIT Kerberos libraries at this time.
+
+   If you are using this method there is no longer a need to change the
+   WinRM service authentication settings. You can simply do a
+   'winrm quickconfig' on your server or enable WinRM via group policy and
+   everything should be working.
+
+2. Multi-Instance support:  The SOAP back-end has been completely gutted
+   and is now using some of the Savon core libraries for parsing and
+   building packets. Moving away from Handsoap allows multiple instances
+   to be created because the SOAP backend is no longer a Singleton type
+   class.
+
+--------------------------------------------------------------------------
+!!!SHOUTS OUT!!!
+--------------------------------------------------------------------------
+Thanks to Seth Chisamore (https://github.com/schisamo) of Opscode for his input and patches.
 --------------------------------------------------------------------------
-TO USE:
-require 'winrm'
-# See REQUIRED GEMS below
 
-gem install -r winrm
 
-REQUIRED GEMS: (These should automatically install with the winrm gem)
-# Handsoap
-gem install -r handsoap
-# Nokogiri XML Parser
-gem install -r nokogiri
-# HttpClient
-gem install -r httpclient
-# NTLM Library
-gem install -r rubyntlm
-#UUID Library
-gem install -r uuid
+INSTALL:
+gem install -r winrm
+.. on the server 'winrm quickconfig' as admin
 
+USE:
+require 'winrm'
 
 EXAMPLE:
 require 'winrm'
-WinRM::WinRM.endpoint = 'https://mywinrmhost:5986/wsman'
-WinRM::WinRM.set_auth('user','password')
-winrm = WinRM::WinRM.instance
-outputps = winrm.powershell 'script.ps1'
-outputcmd = winrm.cmd 'ipconfig'
-
-To specify manually where your CA certificate store is use this:
-WinRM::WinRM.set_ca_trust_path('/etc/ssl/certs')
+endpoint = http://mywinrmhost:5985/wsman
+krb5_realm = 'EXAMPLE.COM'
+winrm = WinRM::WinRMWebService.new(endpoint, :kerberos, :realm => krb5_realm)
+winrm.cmd('ipconfig /all') do |stdout, stderr|
+  STDOUT.print stdout
+  STDERR.print stderr
+end
+
+
+CONNECTION TYPES:
+
+BASIC:
+  WinRM::WinRMWebService.new(endpoint, :plaintext, :user => myuser, :pass => mypass)
+BASIC + SSL:
+  WinRM::WinRMWebService.new(endpoint, :ssl, :user => myuser, :pass => mypass)
+KERBEROS:
+  WinRM::WinRMWebService.new(endpoint, :kerberos, :realm => 'MYREALM.COM')
 
 --------------------------------------------------------------------------
 DISCLAIMER:  If you see something that could be done better or would like

data/VERSION

@@ -1 +1 @@
-0.0.6
+1.0.0rc1

data/lib/winrm.rb

@@ -19,81 +19,8 @@
 #############################################################################
 
 # We only what one instance of this class so include Singleton
-require 'singleton'
 require 'date'
-require 'base64'
-require 'uuid'
-require 'kconv'
+require 'kconv' if(RUBY_VERSION.start_with? '1.9') # bug in rubyntlm with ruby 1.9.x
 
-# Class Extensions
-require 'extensions/string'
-
-# Load the backend SOAP infrastructure.  Today this is Handsoap.
-require 'soap/soap_provider'
-
-
-module WinRM
-  class WinRM
-    include Singleton
-
-    attr_reader :winrm
-
-    # Set the endpoint for WinRM Web Services.  
-    # @param [String] endpoint The URL of the endpoint.
-    #   https://myserver:5986/wsman
-    # @param [Integer] version The SOAP version to use.  This defaults to 1
-    #   and you should not need to pass this parameter.
-    def self.endpoint=(endpoint, version = 2)
-      @@endpoint = endpoint
-      SOAP::WinRMWebService.endpoint(:uri => endpoint, :version => version)
-    end
-
-    # Fetch the current endpoint
-    def self.endpoint
-      @@endpoint
-    end
-
-    # Set the SOAP username and password.
-    # @param [String] user The user name
-    # @param [String] pass The password
-    def self.set_auth(user,pass)
-      @@user = user
-      SOAP::WinRMWebService.set_auth(user,pass)
-    end
-
-    def self.set_ca_trust_path(path)
-      SOAP::WinRMWebService.set_ca_trust_path(path)
-    end
-
-    # Set the http driver that the SOAP back-end will use.
-    # @param [Symbol] driver The HTTP driver.  Available drivers:
-    #   :curb, :net_http, :http_client(Default)
-    def self.set_http_driver(driver)
-      Handsoap.http_driver = driver
-    end
-
-    def initialize
-      @winrm = SOAP::WinRMWebService.new
-    end
-
-    # Run a CMD command
-    # @see WinRM::SOAP::WinRMWebService#run_cmd
-    def cmd(command)
-      @winrm.run_cmd(command)
-    end
-
-    # Run a Powershell script
-    # @see WinRM::SOAP::WinRMWebService#run_powershell_script
-    def powershell(script_file)
-      @winrm.run_powershell_script(script_file)
-    end
-
-    # Run a WQL Query
-    # @see WinRM::SOAP::WinRMWebService#run_wql
-    # @see http://msdn.microsoft.com/en-us/library/aa394606(VS.85).aspx
-    def wql(wql)
-      @winrm.run_wql(wql)
-    end
-
-  end # class WinRM
-end
+require 'winrm/helpers/iso8601_duration'
+require 'winrm/soap_provider'

data/lib/{soap → winrm}/exceptions/exceptions.rb

@@ -19,14 +19,15 @@
 #############################################################################
 
 module WinRM
-  module SOAP
-    # Generic WinRM SOAP Error
-    class WinRMWebServiceError < StandardError
-    end
+  # Generic WinRM SOAP Error
+  class WinRMWebServiceError < StandardError
+  end
 
-    # Authorization Error
-    class WinRMAuthorizationError < StandardError
-    end
-  end # SOAP
+  # Authorization Error
+  class WinRMAuthorizationError < StandardError
+  end
+
+  # A Fault returned in the SOAP response. The XML node is a WSManFault
+  class WinRMWSManFault < StandardError; end
 end # WinRM
- 
+

data/lib/winrm/helpers/iso8601_duration.rb

@@ -0,0 +1,37 @@
+# Format an ISO8601 Duration
+module Iso8601Duration
+
+  # Convert the number of seconds to an ISO8601 duration format
+  # @see http://tools.ietf.org/html/rfc2445#section-4.3.6
+  # @param [Fixnum] seconds The amount of seconds for this duration
+  def self.sec_to_dur(seconds)
+    seconds = seconds.to_i
+    iso_str = "P"
+    if(seconds > 604800) # more than a week
+      weeks = seconds / 604800
+      seconds -= (604800 * weeks)
+      iso_str << "#{weeks}W"
+    end
+    if(seconds > 86400) # more than a day
+      days = seconds / 86400
+      seconds -= (86400 * days)
+      iso_str << "#{days}D"
+    end
+    if(seconds > 0)
+      iso_str << "T"
+      if(seconds > 3600) # more than an hour
+        hours = seconds / 3600
+        seconds -= (3600 * hours)
+        iso_str << "#{hours}H"
+      end
+      if(seconds > 60) # more than a minute
+        minutes = seconds / 60
+        seconds -= (60 * minutes)
+        iso_str << "#{minutes}M"
+      end
+      iso_str << "#{seconds}S"
+    end
+
+    iso_str
+  end
+end

data/lib/winrm/http/transport.rb

@@ -0,0 +1,173 @@
+module WinRM
+  module HTTP
+
+    # A generic HTTP transport that utilized HTTPClient to send messages back and forth.
+    # This backend will maintain state for every WinRMWebService instance that is instatiated so it
+    # is possible to use GSSAPI with Keep-Alive.
+    class HttpTransport
+
+      attr_reader :endpoint
+
+      def initialize(endpoint)
+        @endpoint = endpoint.is_a?(String) ? URI.parse(endpoint) : endpoint
+        @httpcli = HTTPClient.new(:agent_name => 'Ruby WinRM Client')
+      end
+
+      def send_request(message)
+        hdr = {'Content-Type' => 'application/soap+xml;charset=UTF-8', 'Content-Length' => message.length}
+        resp = @httpcli.post(@endpoint, message, hdr)
+        if(resp.status == 200)
+          # Version 1.1 of WinRM adds the namespaces in the document instead of the envelope so we have to
+          # add them ourselves here. This should have no affect version 2.
+          doc = Nokogiri::XML(resp.body.content)
+          doc.collect_namespaces.each_pair do |k,v|
+            doc.root.add_namespace((k.split(/:/).last),v) unless doc.namespaces.has_key?(k)
+          end
+          return doc
+        else
+          puts "RESPONSE was #{resp.status}"
+          # TODO: raise error
+        end
+      end
+
+      # This will remove Negotiate authentication for plaintext and SSL because it supercedes Basic
+      # when it shouldn't for these types of transports.
+      def basic_auth_only!
+        auths = @httpcli.www_auth.instance_variable_get('@authenticator')
+        auths.delete_if {|i| i.scheme !~ /basic/i}
+      end
+    end
+
+    class HttpPlaintext < HttpTransport
+      def initialize(endpoint, user, pass)
+        super(endpoint)
+        @httpcli.set_auth(nil, user, pass)
+        basic_auth_only!
+      end
+    end
+
+    # Uses SSL to secure the transport
+    class HttpSSL < HttpTransport
+      def initialize(endpoint, user, pass, ca_trust_path = nil)
+        super(endpoint)
+        @httpcli.set_auth(endpoint, user, pass)
+        @httpcli.ssl_config.set_trust_ca(ca_trust_path) unless ca_trust_path.nil?
+        basic_auth_only!
+      end
+    end
+
+    # Uses Kerberos/GSSAPI to authenticate and encrypt messages
+    class HttpGSSAPI < HttpTransport
+      # @param [String,URI] endpoint the WinRM webservice endpoint
+      # @param [String] realm the Kerberos realm we are authenticating to
+      # @param [String<optional>] service the service name, default is HTTP
+      # @param [String<optional>] keytab the path to a keytab file if you are using one
+      def initialize(endpoint, realm, service = nil, keytab = nil)
+        super(endpoint)
+        service ||= 'HTTP'
+        @service = "#{service}/#{@endpoint.host}@#{realm}"
+        init_krb
+      end
+
+      def set_auth(user,pass)
+        # raise Error
+      end
+
+      def send_request(msg)
+        original_length = msg.length
+        emsg = winrm_encrypt(msg)
+        hdr = {
+          "Connection" => "Keep-Alive",
+          "Content-Type" => "multipart/encrypted;protocol=\"application/HTTP-Kerberos-session-encrypted\";boundary=\"Encrypted Boundary\""
+        }
+
+        body = <<-EOF
+--Encrypted Boundary\r
+Content-Type: application/HTTP-Kerberos-session-encrypted\r
+OriginalContent: type=application/soap+xml;charset=UTF-8;Length=#{original_length}\r
+--Encrypted Boundary\r
+Content-Type: application/octet-stream\r
+#{emsg}--Encrypted Boundary\r
+        EOF
+
+        r = @httpcli.post(@endpoint, body, hdr)
+
+        winrm_decrypt(r.body.content)
+      end
+
+
+      private 
+
+
+      def init_krb
+        @gsscli = GSSAPI::Simple.new(@endpoint.host, @service)
+        token = @gsscli.init_context
+        auth = Base64.strict_encode64 token
+
+        hdr = {"Authorization" => "Kerberos #{auth}",
+          "Connection" => "Keep-Alive",
+          "Content-Type" => "application/soap+xml;charset=UTF-8"
+        }
+        r = @httpcli.post(@endpoint, '', hdr)
+        itok = r.header["WWW-Authenticate"].pop
+        itok = itok.split.last
+        itok = Base64.strict_decode64(itok)
+        @gsscli.init_context(itok)
+      end
+
+      # @return [String] the encrypted request string
+      def winrm_encrypt(str)
+        iov_cnt = 2
+        iov = FFI::MemoryPointer.new(GSSAPI::LibGSSAPI::GssIOVBufferDesc.size * iov_cnt)
+
+        iov0 = GSSAPI::LibGSSAPI::GssIOVBufferDesc.new(FFI::Pointer.new(iov.address))
+        iov0[:type] = (GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_TYPE_HEADER | GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_FLAG_ALLOCATE)
+
+        iov1 = GSSAPI::LibGSSAPI::GssIOVBufferDesc.new(FFI::Pointer.new(iov.address + (GSSAPI::LibGSSAPI::GssIOVBufferDesc.size * 1)))
+        iov1[:type] =  (GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_TYPE_DATA)
+        iov1[:buffer].value = str
+
+        conf_state = FFI::MemoryPointer.new :uint32
+        min_stat = FFI::MemoryPointer.new :uint32
+
+        maj_stat = GSSAPI::LibGSSAPI.gss_wrap_iov(min_stat, @gsscli.context, 1, 0, conf_state, iov, iov_cnt)
+
+        token = [iov0[:buffer].length].pack('L')
+        token += iov0[:buffer].value
+        token += iov1[:buffer].value
+      end
+
+
+      # @return [String] the unencrypted response string
+      def winrm_decrypt(str)
+        iov_cnt = 2
+        iov = FFI::MemoryPointer.new(GSSAPI::LibGSSAPI::GssIOVBufferDesc.size * iov_cnt)
+
+        iov0 = GSSAPI::LibGSSAPI::GssIOVBufferDesc.new(FFI::Pointer.new(iov.address))
+        iov0[:type] = (GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_TYPE_HEADER | GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_FLAG_ALLOCATE)
+
+        iov1 = GSSAPI::LibGSSAPI::GssIOVBufferDesc.new(FFI::Pointer.new(iov.address + (GSSAPI::LibGSSAPI::GssIOVBufferDesc.size * 1)))
+        iov1[:type] =  (GSSAPI::LibGSSAPI::GSS_IOV_BUFFER_TYPE_DATA)
+
+        str.force_encoding('BINARY')
+        str.sub!(/^.*Content-Type: application\/octet-stream\r\n(.*)--Encrypted.*$/m, '\1')
+
+        len = str.unpack("L").first
+        iov_data = str.unpack("LA#{len}A*")
+        iov0[:buffer].value = iov_data[1]
+        iov1[:buffer].value = iov_data[2]
+
+        min_stat = FFI::MemoryPointer.new :uint32
+        conf_state = FFI::MemoryPointer.new :uint32
+        conf_state.write_int(1)
+        qop_state = FFI::MemoryPointer.new :uint32
+        qop_state.write_int(0)
+
+        maj_stat = GSSAPI::LibGSSAPI.gss_unwrap_iov(min_stat, @gsscli.context, conf_state, qop_state, iov, iov_cnt)
+
+        Nokogiri::XML(iov1[:buffer].value)
+      end
+
+    end
+  end
+end # WinRM

data/lib/winrm/soap_provider.rb

@@ -0,0 +1,43 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+#
+# This file is part of WinRM.
+# 
+# WinRM is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# WinRM is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with WinRM.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+require 'httpclient'
+require 'savon/soap/xml'
+require 'uuid'
+require 'gssapi'
+require 'base64'
+require 'nokogiri'
+
+module WinRM
+  NS_SOAP_ENV    ='s'   # http://www.w3.org/2003/05/soap-envelope
+  NS_ADDRESSING  ='a'   # http://schemas.xmlsoap.org/ws/2004/08/addressing
+  NS_CIMBINDING  ='b'   # http://schemas.dmtf.org/wbem/wsman/1/cimbinding.xsd
+  NS_ENUM        ='n'   # http://schemas.xmlsoap.org/ws/2004/09/enumeration
+  NS_TRANSFER    ='x'   # http://schemas.xmlsoap.org/ws/2004/09/transfer
+  NS_WSMAN_DMTF  ='w'   # http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
+  NS_WSMAN_MSFT  ='p'   # http://schemas.microsoft.com/wbem/wsman/1/wsman.xsd
+  NS_SCHEMA_INST ='xsi' # http://www.w3.org/2001/XMLSchema-instance
+  NS_WIN_SHELL   ='rsp' # http://schemas.microsoft.com/wbem/wsman/1/windows/shell
+  NS_WSMAN_FAULT = 'f'  # http://schemas.microsoft.com/wbem/wsman/1/wsmanfault
+end
+
+require 'winrm/exceptions/exceptions'
+require 'winrm/winrm_service'
+require 'winrm/http/transport'