summaryrefslogtreecommitdiff
path: root/lib/chef/resource/registry_key.rb
blob: 6c17146fcbcceca29c7fde99a9e12482162eada9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
# Author:: Prajakta Purohit (<prajakta@chef.io>)
# Author:: Lamont Granquist (<lamont@chef.io>)
#
# Copyright:: Copyright (c) Chef Software Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

require_relative "../resource"
require_relative "../digester"

class Chef
  class Resource
    class RegistryKey < Chef::Resource
      unified_mode true

      provides(:registry_key) { true }

      description "Use the **registry_key** resource to create and delete registry keys in Microsoft Windows."
      examples <<~'DOC'
      **Create a registry key**

      ```ruby
      registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do
        values [{
          name: 'EnableLUA',
          type: :dword,
          data: 0
        }]
        action :create
      end
      ```

      **Create a registry key with binary data: "\x01\x02\x03"**:

      ```ruby
      registry_key 'HKEY_CURRENT_USER\ChefTest' do
        values [{
          :name => "test",
          :type => :binary,
          :data => [0, 1, 2].map(&:chr).join
        }]
        action :create
      end
      ```

      **Create 32-bit key in redirected wow6432 tree**

      In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be “Found 32-bit key” if they are run on a version of Microsoft Windows that is 64-bit:

      ```ruby
      registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do
        architecture :i386
        recursive true
        action :create
      end
      ```

      **Set proxy settings to be the same as those used by Chef Infra Client**

      ```ruby
      proxy = URI.parse(Chef::Config[:http_proxy])
      registry_key 'HKCU\Software\Microsoft\path\to\key\Internet Settings' do
        values [{name: 'ProxyEnable', type: :reg_dword, data: 1},
                {name: 'ProxyServer', data: "#{proxy.host}:#{proxy.port}"},
                {name: 'ProxyOverride', type: :reg_string, data: <local>},
               ]
        action :create
      end
      ```

      **Set the name of a registry key to "(Default)"**

      ```ruby
      registry_key 'Set (Default) value' do
        key 'HKLM\Software\Test\Key\Path'
        values [
          {name: '', type: :string, data: 'test'},
        ]
        action :create
      end
      ```

      **Delete a registry key value**

      ```ruby
      registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do
        values [{
          name: 'NoAutoRebootWithLoggedOnUsers',
          type: :dword,
          data: ''
          }]
        action :delete
      end
      ```

      Note: If data: is not specified, you get an error: Missing data key in RegistryKey values hash

      **Delete a registry key and its subkeys, recursively**

      ```ruby
      registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do
        recursive true
        action :delete_key
      end
      ```

      Note: Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client.
      DOC

      state_attrs :values

      default_action :create
      allowed_actions :create, :create_if_missing, :delete, :delete_key

      # Some registry key data types may not be safely reported as json.
      # Example (CHEF-5323):
      #
      # registry_key 'HKEY_CURRENT_USER\\ChefTest2014' do
      #   values [{
      #     :name => "ValueWithBadData",
      #     :type => :binary,
      #     :data => 255.chr * 1
      #   }]
      #   action :create
      # end
      #
      # will raise Encoding::UndefinedConversionError: "\xFF" from ASCII-8BIT to UTF-8.
      #
      # To avoid sending data that cannot be nicely converted for json, we have
      # the values method return "safe" data if the data type is "unsafe". Known "unsafe"
      # data types are :binary, :dword, :dword-big-endian, and :qword. If other
      # criteria generate data that cannot reliably be sent as json, add that criteria
      # to the needs_checksum? method. When unsafe data is detected, the values method
      # returns an md5 checksum of the listed data.
      #
      # :unscrubbed_values returns the values exactly as provided in the resource (i.e.,
      # data is not checksummed, regardless of the data type/"unsafe" criteria).
      #
      # Future:
      # If we have conflicts with other resources reporting json incompatible state, we
      # may want to extend the state_attrs API with the ability to rename POST'd attrs.
      #
      # See lib/chef/resource_reporter.rb for more information.
      attr_reader :unscrubbed_values

      def initialize(name, run_context = nil)
        super
        @values, @unscrubbed_values = [], []
      end

      property :key, String, name_property: true

      VALID_VALUE_HASH_KEYS = %i{name type data}.freeze

      def values(arg = nil)
        if not arg.nil?
          if arg.is_a?(Hash)
            @values = [ Mash.new(arg).symbolize_keys ]
          elsif arg.is_a?(Array)
            @values = []
            arg.each do |value|
              @values << Mash.new(value).symbolize_keys
            end
          else
            raise ArgumentError, "Bad type for RegistryKey resource, use Hash or Array"
          end

          @values.each do |v|
            raise ArgumentError, "Missing name key in RegistryKey values hash" unless v.key?(:name)

            v.each_key do |key|
              raise ArgumentError, "Bad key #{key} in RegistryKey values hash" unless VALID_VALUE_HASH_KEYS.include?(key)
            end
            raise ArgumentError, "Type of name => #{v[:name]} should be string" unless v[:name].is_a?(String)

            if v[:type]
              raise ArgumentError, "Type of type => #{v[:type]} should be symbol" unless v[:type].is_a?(Symbol)
            end
          end
          @unscrubbed_values = @values
        elsif instance_variable_defined?(:@values)
          scrub_values(@values)
        end
      end

      property :recursive, [TrueClass, FalseClass], default: false
      property :architecture, Symbol, default: :machine, equal_to: %i{machine x86_64 i386}

      private

      def scrub_values(values)
        scrubbed = []
        values.each do |value|
          scrubbed_value = value.dup
          if needs_checksum?(scrubbed_value)
            data_io = StringIO.new(scrubbed_value[:data].to_s)
            scrubbed_value[:data] = Chef::Digester.instance.generate_checksum(data_io)
          end
          scrubbed << scrubbed_value
        end
        scrubbed
      end

      # Some data types may raise errors when sent as json. Returns true if this
      # value's data may need to be converted to a checksum.
      def needs_checksum?(value)
        unsafe_types = %i{binary dword dword_big_endian qword}
        unsafe_types.include?(value[:type])
      end

    end
  end
end