ruby-jss 1.0.3b4 → 1.0.3b5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b0bf5083913e6e9d2cf6588f229109ef8013fe64d5ea522c4a0031cc1ed2c88
-  data.tar.gz: 6cd578111688ad29bba7595e522a2bfd97b298e2c85fb7a3e14a4d92c8c50980
+  metadata.gz: 4484b1e28fa48b3359c0fa3e1f946f516e1606ba3e699f16226d98fd83a4d87f
+  data.tar.gz: 70e69a2e1e38c7f2106661ee58eced3cd60d132c7c11b22449a4b5cfca210277
 SHA512:
-  metadata.gz: f1d0a5b50436e1c66dff5079ee1a1c1bb72298c527db8682adff99db986cca3c4993e02c01bdf5117e9be5e6c6020788a47d5c4eee4e1b744c7e54a9ea649021
-  data.tar.gz: 3913594f7506a232b29f004790645762a52f47fcae1968c35e3cd17c633cfe165d6d26ec35d8506c93cb5658cbf9c6b70f863de6f6da29d371381789f1f059ed
+  metadata.gz: 2075c974cf726e611d170ba82eafd202b5d3028201359ef57648654ca3c71df31f8237046891891d362f28bbeb8202d11a89c0e28a71eea6b1928d3a54824a8e
+  data.tar.gz: c134e904917e2b0557134d856db08a38cbc3a60aed6ceac7ace77144b070155b8771e00dd0fb33d484d4b96d80567991eab53ef8862d372b47be98d70e6d2c0b

data/CHANGES.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - LDAPServer.server_for_user and .server_for_group class methods, return the id of the first LDAP server containing the given user or group
 
-- Client.homdir(user) and Client.do_not_disturb?(user)
+- Client.homedir(user) and Client.do_not_disturb?(user)
 
 - Package.all_filenames, .orphaned_files, and .missing_files class methods. WARNING - these are very slow since they must instantiate every package.
 
@@ -25,6 +25,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     `JSS.api.connect server: 'myjss.myserver.edu', server_path: 'dev_mgmt/jssweb', port: 8443 [...]`
   (Thanks @christopher.kemp!)
 
+- Packages in Jamf Pro 10.10 and higher now include checksum data (`hash_type` and `hash_value` in the raw data) via the classic API. This has been integrated into JSS::Package via the following methods:
+  - New Class Method `JSS::Package.calculate_checksum(filepath, type)` calcuates an MD5 or SHA_512 hash for an arbtrary file.
+  - New Instance Methods:
+    - `JSS::Package#checksum` returns the checksum value
+    - `JSS::Package#checksum_type` returns the string 'MD5' or 'SHA_512' ('SHA_512' if no checksum is set)
+    - `JSS::Package#caluclate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true )` recalculates and returns the checksum from a local file or the master dist. point. Doesn't change the Package instance
+    - `JSS::Package#checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true)` recalculates the checksum from a local file or the master dist. point, and returns Boolean true if it matches the stored one, false if not. Always false if there is no stored checksum. Doesn't change the Package instance
+    - `JSS::Package#reset_checksum(type: nil, local_file: nil,  rw_pw: nil, ro_pw: nil, unmount: true)` recalculates and resets the checksum from a local file or the master dist. point. The instance must be saved back to the server for the new checksum to stick,
+  - Modified Instance Method `JSS::Package#upload_master_file` now takes a `cksum:` parameter, 'MD5' or 'SHA_512' ('SHA_512' by default)  Any other value means 'don't use a checksum on this package'
+
+  NOTE: Checksum calculation can be slow.
+  WARNING: when using a local file to calculate checksums, BE 100% SURE it is identical to the file on the master distribution point, or you will get an invalid checksum.
+
+
 ### Fixed
 - JSS::MobileDevice.update now returns the device's jss id, as advertised.
 

data/lib/jss.rb

@@ -54,6 +54,7 @@ module JSS
   require 'open3'
   require 'English'
   require 'json'
+  require 'digest'
 
   ###################
   ### Gems

data/lib/jss/api_object/mdm.rb

@@ -453,7 +453,7 @@ module JSS
 
         # make sure all of them are managed, or else the API will raise a 400
         # 'Bad Request' when sending the command to an unmanaged target
-        all_mgd = self.map_all_ids_to(:managed).select { |_id, mgd| mgd }.keys
+        all_mgd = self.map_all_ids_to(:managed, api: api).select { |_id, mgd| mgd }.keys
 
         targets.each do |target_id|
           raise JSS::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id

data/lib/jss/api_object/package.rb

@@ -23,6 +23,9 @@
 #
 #
 
+# TEMPPORARY
+require 'digest'
+
 module JSS
 
   # Classes
@@ -82,6 +85,21 @@ module JSS
     # The table in the database for this object
     DB_TABLE = 'packages'.freeze
 
+    # The hash_type value in the API for md5
+    CHECKSUM_HASH_TYPE_MD5 = 'MD5'.freeze
+
+    # The hash_type value in the API for sha512
+    CHECKSUM_HASH_TYPE_SHA512 = 'SHA_512'.freeze
+
+    # Mapping of the hash types to the maching Digest modules
+    # See {#calculate_checksum}
+    CHECKSUM_HASH_TYPES = {
+      CHECKSUM_HASH_TYPE_MD5 => Digest::MD5,
+      CHECKSUM_HASH_TYPE_SHA512 => Digest::SHA512
+    }.freeze
+
+    DEFAULT_CHECKSUM_HASH_TYPE = CHECKSUM_HASH_TYPE_SHA512
+
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}
@@ -159,6 +177,21 @@ module JSS
       all_filenames(api: api) - files_on_mdp
     end
 
+    # Given a file path, and hash type, generate the checksum for an arbitrary
+    # file.
+    #
+    # @param filepath [String, Pathname] The file to checksum
+    #
+    # @param type [String ] One of the keys of CHECKSUM_HASH_TYPES, either
+    #    CHECKSUM_HASH_TYPE_MD5 or CHECKSUM_HASH_TYPE_SHA512
+    #
+    # @return [String] The checksum of the file
+    #
+    def self.calculate_checksum(filepath, type = DEFAULT_CHECKSUM_HASH_TYPE )
+      raise ArgumentError, 'Unknown checksum hash type' unless CHECKSUM_HASH_TYPES.key? type
+      CHECKSUM_HASH_TYPES[type].file(filepath).hexdigest
+    end
+
     # Attributes
     #####################################
 
@@ -207,6 +240,14 @@ module JSS
     # @return [Boolean] does this pkg cause a notification to be sent on self-heal?
     attr_reader :send_notification
 
+    # @ @return [Symbol] The checksum hash type used to generate the checksum value,
+    #  either :md5 or :sha512, defaults to :sha512 if there is no checksum yet.
+    attr_reader :checksum_type
+
+    # @return [String, nil] the checksum value for the package file on the
+    #   dist. point, if it's been calculated.
+    attr_reader :checksum
+
     # @see JSS::APIObject#initialize
     #
     def initialize(args = {})
@@ -231,6 +272,10 @@ module JSS
       @send_notification = @init_data[:send_notification]
       @switch_with_package = @init_data[:switch_with_package] || DO_NOT_INSTALL
 
+      @checksum = @init_data[:hash_value] #ill be nil if no checksum
+      @checksum_type = @checksum ? @init_data[:hash_type] : DEFAULT_CHECKSUM_HASH_TYPE
+
+
       # the receipt is the filename with any .zip extension removed.
       @receipt = @filename ? (JSS::Client::RECEIPTS_FOLDER + @filename.to_s.sub(/.zip$/, '')) : nil
     end # init
@@ -516,9 +561,12 @@ module JSS
     #
     # @param unmount[Boolean] whether or not ot unount the distribution point when finished.
     #
+    # @param chksum [String] the constants CHECKSUM_HASH_TYPE_SHA512 or
+    #   CHECKSUM_HASH_TYPE_MD5. Anything else means don't calc.
+    #
     # @return [void]
     #
-    def upload_master_file(local_file_path, rw_pw, unmount = true)
+    def upload_master_file(local_file_path, rw_pw, unmount = true, chksum: DEFAULT_CHECKSUM_HASH_TYPE )
       raise JSS::NoSuchItemError, 'Please create this package in the JSS before uploading it.' unless @in_jss
 
       mdp = JSS::DistributionPoint.master_distribution_point api: @api
@@ -557,14 +605,126 @@ module JSS
         destination = destination.to_s + '.zip'
         @filename = zipfile.basename.to_s
         @need_to_update = true
-        update
       end # if directory
 
       FileUtils.copy_entry local_path, destination
 
+      if CHECKSUM_HASH_TYPES.keys.include? chksum
+        @checksum_type = chksum
+        @checksum = calculate_checksum local_path, chksum
+        @need_to_update = true
+      end
+
+      update if @need_to_update
+
       mdp.unmount if unmount
     end # upload
 
+    # Using either a local file, or the file on the master dist. point,
+    # re-set the checksum for this package. Call #update to save the
+    # new one to the JSS.
+    #
+    # BE VERY CAREFUL if using a local copy of the file - make sure its
+    # identical to the one on the dist point.
+    #
+    # This can be used to change the checksum type, and by default will use
+    # DEFAULT_CHECKSUM_HASH_TYPE ('SHA_512')
+    #
+    # @param @see calculate_checksum
+    #
+    # @return [void]
+    #
+    def reset_checksum(type: nil, local_file: nil,  rw_pw: nil, ro_pw: nil, unmount: true)
+      type ||= DEFAULT_CHECKSUM_HASH_TYPE
+
+      new_checksum = calculate_checksum(
+        type: type,
+        local_file: local_file,
+        rw_pw: rw_pw,
+        ro_pw: ro_pw,
+        unmount: unmount
+      )
+      return if @checksum == new_checksum
+
+      @checksum_type = type
+      @checksum = new_checksum
+      @need_to_update = true
+    end
+
+    # Caclulate and return the checksum hash for a given local file, or the file
+    # on the master dist point if no local file is given.
+    #
+    # @param type [String] The checksum hash type, one of the keys of
+    #   CHECKSUM_HASH_TYPES
+    #
+    # @param local_file [String, Pathname] A local copy of the pkg file. BE SURE
+    #   it's identical to the one on the server. If omitted, the master dist.
+    #   point will be mounted and the file read from there.
+    #
+    # @param rw_pw [String] The read-write password for mounting the master dist
+    #   point. Either this or the ro_pw must be provided if no local_file
+    #
+    # @param ro_pw [String] The read-onlypassword for mounting the master dist
+    #   point. Either this or the rw_pw must be provided if no local_file
+    #
+    # @param unmount [Boolean] Unmount the master dist point after using it.
+    #   Only used if the dist point is mounted. default: true
+    #
+    # @return [String] The calculated checksum
+    #
+    def calculate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true )
+      type ||= DEFAULT_CHECKSUM_HASH_TYPE
+      mdp = JSS::DistributionPoint.master_distribution_point api: @api
+
+      if local_file
+        file_to_calc = local_file
+      else
+        if rw_pw
+          dppw = rw_pw
+          mnt = :rw
+        elsif ro_pw
+          dppw = ro_pw
+          mnt = :ro
+        else
+          raise ArgumentError, 'Either rw_pw: or ro_pw: must be provided'
+        end
+        file_to_calc = mdp.mount(dppw, mnt) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
+      end
+      new_checksum = self.class.calculate_checksum(file_to_calc, type)
+      mdp.unmount if unmount && mdp.mounted?
+      new_checksum
+    end
+
+    # Is the checksum for this pkg is valid?
+    #
+    # @param local_file [String, Pathname] A local copy of the pkg file. BE SURE
+    #   it's identical to the one on the server. If omitted, the master dist.
+    #   point will be mounted and the file read from there.
+    #
+    # @param rw_pw [String] The read-write password for mounting the master dist
+    #   point. Either this or the ro_pw must be provided if no local_file
+    #
+    # @param ro_pw [String] The read-onlypassword for mounting the master dist
+    #   point. Either this or the rw_pw must be provided if no local_file
+    #
+    # @param unmount [Boolean] Unmount the master dist point after using it.
+    #   Only used if the dist point is mounted. default: true
+    #
+    # @return [Boolean] false if there is no checksum for this pkg, otherwise,
+    #   does the calculated checksum match the one stored for the pkg?
+    #
+    def checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true)
+      return false unless @checksum
+      new_checksum = calculate_checksum(
+        type: @checksum_type,
+        local_file: local_file,
+        rw_pw: rw_pw,
+        ro_pw: ro_pw,
+        unmount: unmount
+      )
+      new_checksum == @checksum
+    end
+
     # Change the name of a package file on the master distribution point.
     #
     # @param new_file_name[String]
@@ -595,6 +755,8 @@ module JSS
       nil
     end # update_master_filename
 
+
+
     # Delete the filename from the master distribution point, if it exists.
     #
     # If you'll be uploading several files you can specify unmount as false, and do it manually when all
@@ -856,6 +1018,13 @@ module JSS
       pkg.add_element('required_processor').text = @required_processor.to_s.empty? ? 'None' : @required_processor
       pkg.add_element('send_notification').text = @send_notification
       pkg.add_element('switch_with_package').text = @switch_with_package
+      # if there's no checksum value for this pkg, don't even include the
+      # hash_type and hash_value in the XML, they'll stay whatever
+      # the JSS already has (which is usuall type=MD5, and value='')
+      if @checksum
+        pkg.add_element('hash_type').text = @checksum_type
+        pkg.add_element('hash_value').text = @checksum
+      end
       add_category_to_xml(doc)
       doc.to_s
     end # rest xml

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '1.0.3b4'.freeze
+  VERSION = '1.0.3b5'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 1.0.3b4
+  version: 1.0.3b5
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-22 00:00:00.000000000 Z
+date: 2019-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist