ruby-amt 0.1.0

data/lib/amt/service/security_administration/structures.rb

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+
+require 'amt/service/security_administration'
+require 'amt/utility'
+
+module AMT
+  module Service
+    class SecurityAdministration
+
+      # Enumeration containing names of AMT interfaces that can be enabled/disabled. Used for
+      # SecurityAdministration#set_enabled_interfaces and
+      # SecurityAdministration#get_enabled_interfaces.
+      class EnabledInterface < AMT::Utility::Enum
+        multi_add %w[WebUI SerialOverLAN IdeRedirection]
+      end
+
+      # The AMT SOAP interface enumeration. Used for SecurityAdministration#set_tls_options
+      # and SecurityAdministration#get_tls_options.
+      class Interface < AMT::Utility::Enum
+        multi_add %w[NetworkInterface LocalHostInterface]
+      end
+
+      # The TLS Authentication method enumeration. Used for SecurityAdministration#set_tls_options
+      # and SecurityAdministration#get_tls_options.
+      class TlsAuthentication < AMT::Utility::Enum
+        multi_add %w[NoAuth ServerAuth MutualAuth]
+      end
+
+      # Struct class containing version information as returned by
+      # SecurityAdministration#get_core_version.
+      CoreVersion = Struct.new(:major, :minor, :micro)
+
+      # Mapping of provisioning mode name to value. Used for SecurityAdministration#unprovision and
+      # SecurityAdministration#get_provisioning_mode.
+      class ProvisioningMode < AMT::Utility::Enum
+        multi_add(0 => :current, 1 => :enterprise, 2 => :small_business, 3 => :remote_connectivity)
+      end
+
+      # Struct class containing information about an user ACL. The +user+ field may either contain a
+      # binary String identifying a Kerberos SID or a User class instance, the +access_permission+
+      # field contains an instance of AccessPermission and +realms+ contains a list of UserAclRealm
+      # instances. Used for SecurityAdministration#add_user_acl_entry_ex and
+      # SecurityAdministration#update_user_acl_entry_ex.
+      UserAclEntryEx = Struct.new(:user, :access_permission, :realms)
+
+      # Class containing information about a user. Either a plain text password or an already hashed
+      # password must be provided. If a plain text password is provided, the hashed password is
+      # automatically calculated.
+      class User
+
+        # The username to be used. May only contain 7-bit ASCII characters, in the range of 33- 126,
+        # excluding ‘:’, ‘,’, ‘<’, ‘>’, ‘&’, and ‘”’ characters. Length is limited to 16 characters.
+        attr_reader :username
+
+        # The password for the user. This or #hashed_password must be set.
+        attr_reader :password
+
+        # The hashed password for the user. This or #password must be set.
+        attr_reader :hashed_password
+
+
+        # Create a new User object with the given +username+ and, optionally, +password+.
+        def initialize(username, password = nil)
+          self.username = username
+          self.password = password
+        end
+
+        # Contains the characters that are allowed in the username.
+        ALLOWED_USERNAME_CHARS = (33..126).to_a - ":,<>&\"".unpack('c*')
+
+        # Set the username to +value+. If the username is not valid, an ArgumentError is raised.
+        def username=(value)
+          value.each_byte do |b|
+            ALLOWED_USERNAME_CHARS.include?(b) || raise(ArgumentError, "invalid character in username")
+          end
+          raise(ArgumentError, 'username length is limited to 16 characters') if value.length > 16
+          raise(ArgumentError, 'username must not be empty') if value.length == 0
+          @username = value
+        end
+
+        # Set the #password to +value+ and clear the #hashed_password.
+        def password=(value)
+          @hashed_password, @password = nil, value
+        end
+
+        # Set the #hashed_password to +value+ and clear the #password.
+        def hashed_password=(value)
+          @password, @hashed_password = nil, value
+        end
+
+      end
+
+      # Access permissions enumeration. Used in the UserAclEntryEx structure.
+      class AccessPermission < AMT::Utility::Enum
+        multi_add %w[LocalAccessPermission NetworkAccessPermission AnyAccessPermission]
+      end
+
+      # The user ACL realms enumeration. Used in the UserAclEntryEx structure.
+      class UserAclRealm < AMT::Utility::Enum
+        multi_add(0 => :invalid, 1 => :rcs, 2 => :redirection, 3 => :pt_administration,
+                  4 => :hardware_asset, 5 => :remote_control, 6 => :storage,
+                  7 => :event_manager, 8 => :storage_admin, 9 => :agent_presence_local,
+                  10 => :agent_presence_remote, 11 => :circuit_breaker, 12 => :network_time,
+                  13 => :general_info, 14 => :firmware_update, 15 => :eit, 16 => :local_un,
+                  17 => :endpoint_access_control, 18 => :endpoint_access_control_admin,
+                  19 => :event_log_reader, 20 => :security_audit_log, 21 => :user_access_control,
+                  22 => :reserved, 23 => :anti_theft)
+      end
+
+      # Struct class containing the fields for a global power policy (used by
+      # SecurityAdministration#set_global_power_policy and
+      # SecurityAdministration#get_global_power_policy).
+      GlobalPowerPolicy = Struct.new(:idle_wake_timeout)
+
+    end
+  end
+end

data/lib/amt/system.rb

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+
+##
+# This is the API documentation for ruby-amt!
+#
+# Have a look at the \AMT module which provides a good starting point!
+
+
+#
+# The ruby-amt library provides access to the SOAP services provided by Intel AMT devices. Before
+# you decide whether to use the library or not, you should know the following:
+#
+# * The library has been designed to be used with Intel AMT 5.0 devices. This is the reason why no
+#   deprecated methods have been implemented.
+#
+# * Furthermore, the library has been designed to be used with Intel AMT devices in SMB mode. So
+#   SOAP methods which are only useful for devices in Enterprise Mode have not been implemented. One
+#   reason is that I don't have access to devices in Enterprise Mode and therefore cannot test these
+#   methods.
+#
+# = Short Overview
+#
+# The library provides a "low-level" implementation of the client side of the SOAP services (as
+# classes in AMT::Service) as well as a class (AMT::System) for high-level access. The adjective
+# "low-level" is not really correct since the implementation of the client side of the SOAP services
+# is not done by generating code from WSDL files (which normally results in a direct mapping of the
+# SOAP methods and data structures) but by hand-crafting the code and providing simple but adequate
+# data structures.
+#
+# So, although the SOAP service classes directly represent SOAP services and their methods, their
+# usage in an application is actually quite simple. However, there are some AMT work flows which
+# require calling more than one method or getting available states before actually setting
+# something. This can easily be overlooked by people not acquainted with Intel AMT. Therefore there
+# exists a class for high-level access to the AMT functionality of a system which takes this burden
+# of you.
+#
+# = Library Organization
+#
+# This module houses all modules/classes that are in the ruby-amt library. There are three main
+# modules/classes:
+#
+# [AMT::Service]
+#   This module contains all SOAP service classes. There is a one-to-one mapping from
+#   the Intel AMT SOAP services to classes in this module. Note that not all SOAP services are
+#   implemented because some are not really useful for a management application.
+#
+# [AMT::Utility]
+#   This module houses utility classes that are used by other classes (mostly the service classes).
+#
+# [AMT::System]
+#   This is the class that can be used for high-level access to the functionality of an AMT system.
+#
+# = Library Usage
+#
+# == Direct use of SOAP Service Classes
+#
+# All service classes are derived from AMT::Service::Basic and have the same initialization
+# parameters. You need to provide at least the hostname of the AMT device, a username and a
+# password.
+#
+# You don't need to load an individual service class, just use
+#
+#   require 'amt/service'
+#
+# since this will automatically load any service class and any data structures that are needed on
+# demand.
+#
+# For example, the AMT::Service::RemoteControl service can be created like this:
+#
+#   rcs = AMT::Service::RemoteControl.new('amt.example.com', 'admin', 'P@ssw0rD')
+#
+# After that you can just call the method you would like to invoke on the AMT system. But before
+# that you should read the method description sothat you know what parameters to pass. Since the
+# SOAP service classes are not created from WSDL files, they provide a nicer, more Ruby like
+# interface to the SOAP methods. However, this also means that the method signature sometimes
+# differs a little bit from the method signature as defined in the "Network Interface Guide" (which
+# can be found in the Intel AMT SDK).
+#
+# Take the AMT::Service::RemoteControl#get_system_power_state as example:
+#
+#   sps = rcs.get_system_power_state
+#
+# Since this method takes no parameters, there is no difference in this respect. The method would
+# nominally return a bit structure as an unsigned 32 bit integer. However, this has been changed
+# sothat it returns an instance of AMT::Service::RemoteControl::SystemPowerState which provides easy
+# access to the fields of the bit structure. For example:
+#
+#   sps.power_state         # => :s0
+#   sps.watchdog_expired?   # => false
+#   sps.power_source        # => :ac
+#
+# Such a conversion of input or output arguments is true for all implemented methods. The special
+# data structures needed by a service are defined in the namespace of the service. For example, all
+# data structures needed as input or returned as output for the RemoteControl service are defined
+# unter AMT::Service::RemoteControl.
+#
+# So how does one provide input parameters? We take the AMT::Service::RemoteControl#remote_control
+# method as example. You can learn from the method description that it has one mandatory and several
+# optional arguments. Additionally, it is stated which type the arguments have. In its simplest
+# form, one needs to provide just a value for the +command+ parameter which should be an instance of
+# AMT::Service::RemoteControl::RemoteControlCommand. Checking out the class we see that it is a
+# subclass of AMT::Utility::Enum. This allows us to use any of the following ways to power up an AMT
+# system which is currently powered down:
+#
+#   rcs.remote_control(AMT::Service::RemoteControl::RemoteControlCommand.for(:0x11))
+#   rcs.remote_control(AMT::Service::RemoteControl::RemoteControlCommand.for(:power_up))
+#   rcs.remote_control(0x11)
+#   rcs.remote_control(:power_up)
+#
+# As you can see, one doesn't actually need to create an instance of the RemoteControlCommand class,
+# one just needs to provide either a valid enumeration value or enumeration name! <b>This is true
+# everywhere a subclass of AMT::Utility::Enum is expected.</b>
+#
+# A simliar short-cut is available when an instance of a subclass of AMT::Utility::BitStruct is
+# expected - see AMT::Utility::BitStruct.new !
+#
+# Here is a final example with some optional parameters:
+#
+#   rcs.remote_control(:power_up, 343, :boot_options => [:lock_keyboard], :special_command => :pxe_boot)
+#
+#
+# == High-level Interface
+#
+# The high-level interface is not implemented currently.
+#
+module AMT
+
+  # High-level access to AMT functionality.
+  #
+  # NOT IMPLEMENTED
+  class System
+  end
+
+end

data/lib/amt/utility.rb

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+module AMT
+
+  # This module houses utility classes that are used by the other AMT classes.
+  module Utility
+
+    autoload :BitStruct, 'amt/utility/bit_struct'
+    autoload :Enum, 'amt/utility/enum'
+
+
+    # Create a UUID string from binary data which can either have a length of 16 characters (then it
+    # is considered to be a binary UUID) or a length of 32 characters (an already unpacked binary
+    # UUID).
+    def self.binary_to_uuid(data)
+      data = data.unpack('H32').first if data.length == 16
+      a = data.scan(/../)
+      a[0,4].reverse.join('') + "-" + a[4,2].reverse.join('') + "-" + a[6,2].reverse.join('') +
+        "-" + a[8,2].join('') + "-" + a[10,6].join('')
+    end
+
+    # Convert a UUID string to binary data.
+    def self.uuid_to_binary(uuid)
+      [uuid[0,8].scan(/../).reverse.join('') +
+       uuid[9,4].scan(/../).reverse.join('') +
+       uuid[14,4].scan(/../).reverse.join('') +
+       uuid[19,4].scan(/../).join('') +
+       uuid[24,12].scan(/../).join('')].pack('H32')
+    end
+
+  end
+
+end

data/lib/amt/utility/bit_struct.rb

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+
+module AMT
+
+  module Utility
+
+    # A very simple base class which can be used to extract information from a number based on its
+    # bits, or to set it.
+    #
+    # It isn't useful to create objects directly from this class but one should create a subclass
+    # and use the provided class methods to define how to interpret the bits of a number.
+    class BitStruct
+
+      # Interpret the bit with the +index+ (starting from zero) as boolean flag named +name+ (should
+      # be a Symbol). If the bit at the index is +1+, the flag is interpreted as +true+. The
+      # optional parameter +desc+ can be used to provide a textual representation of the +true+
+      # state.
+      #
+      # This method also adds accessor methods for the property. For example, if the property is
+      # called +amt_enabled+, the created getter method is called <tt>#amt_enabled?</tt> and the
+      # setter method is called <tt>#amt_enabled!</tt>. Note the trailing question/exclamation
+      # marks.
+      #
+      # Example usage:
+      #
+      #   boolean 5, :amt_enabled, 'AMT is enabled'
+      def self.boolean(index, name, desc = name.to_s)
+        index = (0x1 << index)
+        (@boolean ||= []) << [name, desc]
+        define_method("#{name}?") do
+          @value & index == index
+        end
+        define_method("#{name}!") do
+          @value |= index
+        end
+      end
+
+
+      # Same as BitStruct.boolean but +mask+ defines a bit mask and the value is only +true+ if all
+      # bits specified by the bit mask (ie. all bits that are +1+ in the bit mask) are set.
+      #
+      # Example usage:
+      #
+      #   mboolean 0b101, :amt_enabled, 'AMT is enabled'
+      def self.mboolean(mask, name, desc = name.to_s)
+        (@boolean ||= []) << [name, desc]
+        define_method("#{name}?") do
+          @value & mask == mask
+        end
+        define_method("#{name}!") do
+          @value |= mask
+        end
+      end
+
+
+      # Interpret the bits in the +bit_range+ (starting from zero) as unsigned integer named +name+
+      # (should be a Symbol). The optional parameter +desc+ can be used to provide a textual
+      # representation of the meaning of the value.
+      #
+      # This method also adds accessor methods for the property. For example, if the property is
+      # called +version+, the created getter method is called <tt>#version</tt> and the setter
+      # method is called <tt>#version=</tt>.
+      #
+      # Example usage:
+      #
+      #   unsigned 2..5, :version, 'The integer version of the AMT device'
+      def self.unsigned(bit_range, name, desc = name.to_s)
+        mask = (2**(bit_range.end - bit_range.begin + 1) - 1) << bit_range.begin
+        (@unsigned ||= []) << [name, desc]
+        define_method(name) do
+          (@value & mask) >> bit_range.begin
+        end
+        define_method("#{name}=") do |number|
+          @value |= (number << bit_range.begin) & mask
+        end
+      end
+
+      # Interpret the bits in the +bit_range+ (starting from zero) as unsigned integer value of an
+      # enumeration called +name+ (should be a Symbol).
+      #
+      # The parameter +values+ specifies the mapping from number to meaning (normally a String). The
+      # optional parameter +desc+ can be used to provide a textual representation of the meaning of
+      # the enumeration.
+      #
+      # This method also adds accessor methods for the property. For example, if the property is
+      # called +version+, the created getter method is called <tt>#version</tt> and the setter
+      # method is called <tt>#version=</tt>.
+      #
+      # Example usage:
+      #
+      #   enum 0..1, :device_type, {0 => 'Foo', 1 => 'Bar', 2 => 'Baz', 3 => Quux'}
+      def self.enum(bit_range, name, values, desc = name.to_s)
+        mask = (2**(bit_range.end - bit_range.begin + 1) - 1) << bit_range.begin
+        (@enum ||= []) << [name, values, desc]
+        define_method(name) do
+          values[(@value & mask) >> bit_range.begin]
+        end
+        define_method("#{name}=") do |number|
+          @value |= (number << bit_range.begin) & mask
+        end
+      end
+
+      # Return a hash of all defined fields for this class. The hash keys are <tt>:boolean</tt> for
+      # the boolean properties, <tt>:unsigned</tt> for the unsigned integer properties and
+      # <tt>:enum</tt> for the enumeration properties. The hash values are arrays with information
+      # (depending on the type of the field) about the fields.
+      def self.fields
+        {:boolean => @boolean || [], :unsigned => @unsigned || [], :enum => @enum || []}
+      end
+
+      # The integer value which should be interpreted bit-wise.
+      attr_reader :value
+
+      # Create a new object. If +value+ is an integer, it is used directly and interpreted bit-wise.
+      # If +value+ is an array, it is processed in the following way:
+      #
+      # * symbols are interpreted as boolean fields
+      # * two-item arrays where the first item is a symbol and the second an integer are interpreted
+      #   as unsigned or enum fields (depending in which category the symbol falls).
+      def initialize(value = 0)
+        if value.kind_of?(Integer)
+          @value = value
+        elsif value.kind_of?(Array)
+          @value = 0
+          value.each do |sym, val|
+            if val.nil?
+              send("#{sym}!")
+            else
+              send("#{sym}=", val)
+            end
+          end
+        else
+          raise ArgumentError, 'invalid argument type specified'
+        end
+      end
+
+      def inspect #:nodoc:
+        bools = self.class.fields[:boolean].select {|n,d| send("#{n}?")}.collect {|n, d| n.to_s}
+        unsigns = self.class.fields[:unsigned].collect {|n, d| "#{n}=#{send(n)}"}
+        enum = self.class.fields[:enum].collect {|n, d| "#{n}=#{send(n)}"}
+        "#<#{self.class.name} #{(bools + unsigns + enum).join(', ')}>"
+      end
+
+      # Return an array with textual representations for output purposes of the the fields specified
+      # by +used_fields+.
+      def list(used_fields = [:boolean, :unsigned, :enum])
+        result = []
+        if used_fields.include?(:boolean)
+          result += self.class.fields[:boolean].select {|n,d| send("#{n}?")}.collect {|n,d| d}
+        end
+        if used_fields.include?(:unsigned)
+          result += self.class.fields[:unsigned].collect {|n, d| "#{d}=#{send(n)}"}
+        end
+        if used_fields.include?(:enum)
+          result += self.class.fields[:enum].collect {|n, d| "#{d}=#{send(n)}"}
+        end
+        result
+      end
+
+    end
+
+  end
+
+end