Class: Net::SSH::KnownHosts

Inherits:
Object
  • Object
show all
Defined in:
lib/net/ssh/known_hosts.rb

Overview

Searches an OpenSSH-style known-host file for a given host, and returns all matching keys. This is used to implement host-key verification, as well as to determine what key a user prefers to use for a given host.

This is used internally by Net::SSH, and will never need to be used directly by consumers of the library.

Constant Summary collapse

SUPPORTED_TYPE = 
%w[ssh-rsa ssh-dss
ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source) ⇒ KnownHosts

Instantiate a new KnownHosts instance that will search the given known-hosts file. The path is expanded file File.expand_path.



203
204
205
206
207
 
# File 'lib/net/ssh/known_hosts.rb', line 203

def initialize(source)
  @source = File.expand_path(source)
rescue ArgumentError
  @source = source
end

Instance Attribute Details

#source ⇒ Object (readonly)

The host-key file name that this KnownHosts instance will use to search for keys.



199
200
201
 
# File 'lib/net/ssh/known_hosts.rb', line 199

def source
  @source
end

Class Method Details

.add(host, key, options = {}) ⇒ Object

Looks in all user known host files (see KnownHosts.hostfiles) and tries to add an entry for the given host and key to the first file it is able to.



187
188
189
190
191
192
193
194
 
# File 'lib/net/ssh/known_hosts.rb', line 187

def add(host, key, options = {})
  hostfiles(options, :user).each do |file|
    KnownHosts.new(file).add(host, key)
    return
  rescue SystemCallError
    # try the next hostfile
  end
end

.hostfiles(options, which = :all) ⇒ Object

Looks in the given options hash for the :user_known_hosts_file and :global_known_hosts_file keys, and returns an array of all known hosts files. If the :user_known_hosts_file key is not set, the default is returned (~/.ssh/known_hosts and ~/.ssh/known_hosts2). If :global_known_hosts_file is not set, the default is used (/etc/ssh/ssh_known_hosts and /etc/ssh/ssh_known_hosts2).

If you only want the user known host files, you can pass :user as the second option.



172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/net/ssh/known_hosts.rb', line 172

def hostfiles(options, which = :all)
  files = []

  files += Array(options[:user_known_hosts_file] || %w[~/.ssh/known_hosts ~/.ssh/known_hosts2]) if which == :all || which == :user

  if which == :all || which == :global
    files += Array(options[:global_known_hosts_file] || %w[/etc/ssh/ssh_known_hosts /etc/ssh/ssh_known_hosts2])
  end

  return files
end

.search_for(host, options = {}) ⇒ Object

Searches all known host files (see KnownHosts.hostfiles) for all keys of the given host. Returns an enumerable of keys found.



153
154
155
 
# File 'lib/net/ssh/known_hosts.rb', line 153

def search_for(host, options = {})
  HostKeys.new(search_in(hostfiles(options), host, options), host, self, options)
end

.search_in(files, host, options = {}) ⇒ Object

Search for all known keys for the given host, in every file given in the files array. Returns the list of keys.



159
160
161
 
# File 'lib/net/ssh/known_hosts.rb', line 159

def search_in(files, host, options = {})
  files.flat_map { |file| KnownHosts.new(file).keys_for(host, options) }
end

Instance Method Details

#add(host, key) ⇒ Object

Tries to append an entry to the current source file for the given host and key. If it is unable to (because the file is not writable, for instance), an exception will be raised.



300
301
302
303
304
305
 
# File 'lib/net/ssh/known_hosts.rb', line 300

def add(host, key)
  File.open(source, "a") do |file|
    blob = [Net::SSH::Buffer.from(:key, key).to_s].pack("m*").gsub(/\s/, "")
    file.puts "#{host} #{key.ssh_type} #{blob}"
  end
end

#keys_for(host, options = {}) ⇒ Object

Returns an array of all keys that are known to be associatd with the given host. The host parameter is either the domain name or ip address of the host, or both (comma-separated). Additionally, if a non-standard port is being used, it may be specified by putting the host (or ip, or both) in square brackets, and appending the port outside the brackets after a colon. Possible formats for host, then, are;

"net.ssh.test"
"1.2.3.4"
"net.ssh.test,1.2.3.4"
"[net.ssh.test]:5555"
"[1,2,3,4]:5555"
"[net.ssh.test]:5555,[1.2.3.4]:5555


222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/net/ssh/known_hosts.rb', line 222

def keys_for(host, options = {})
  keys = []
  return keys unless File.readable?(source)

  entries = host.split(/,/)
  host_name = entries[0]
  host_ip = entries[1]

  File.open(source) do |file|
    file.each_line do |line|
      if line.start_with?('@')
        marker, hosts, type, key_content, comment = line.split(' ')
      else
        marker = nil
        hosts, type, key_content, comment = line.split(' ')
      end

      # Skip empty line or one that is commented
      next if hosts.nil? || hosts.start_with?('#')

      hostlist = hosts.split(',')

      next unless SUPPORTED_TYPE.include?(type)

      found = hostlist.any? { |pattern| match(host_name, pattern) } || known_host_hash?(hostlist, entries)
      next unless found

      found = hostlist.include?(host_ip) if options[:check_host_ip] && entries.size > 1 && hostlist.size > 1
      next unless found

      blob = key_content.unpack("m*").first
      raw_key = Net::SSH::Buffer.new(blob).read_key

      keys <<
        if marker == "@cert-authority"
          HostKeyEntries::CertAuthority.new(raw_key, comment: comment)
        else
          HostKeyEntries::PubKey.new(raw_key, comment: comment)
        end
    end
  end

  keys
end

#known_host_hash?(hostlist, entries) ⇒ Boolean

Indicates whether one of the entries matches an hostname that has been stored as a HMAC-SHA1 hash in the known hosts.

Returns:

  • (Boolean) 


284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/net/ssh/known_hosts.rb', line 284

def known_host_hash?(hostlist, entries)
  if hostlist.size == 1 && hostlist.first =~ /\A\|1(\|.+){2}\z/
    chunks = hostlist.first.split(/\|/)
    salt = chunks[2].unpack1("m")
    digest = OpenSSL::Digest.new('sha1')
    entries.each do |entry|
      hmac = OpenSSL::HMAC.digest(digest, salt, entry)
      return true if [hmac].pack("m").chomp == chunks[3]
    end
  end
  false
end

#match(host, pattern) ⇒ Object 



267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/net/ssh/known_hosts.rb', line 267

def match(host, pattern)
  if pattern.include?('*') || pattern.include?('?')
    # see man 8 sshd for pattern details
    pattern_regexp = pattern.split('*', -1).map do |x|
      x.split('?', -1).map do |y|
        Regexp.escape(y)
      end.join('.')
    end.join('.*')

    host =~ Regexp.new("\\A#{pattern_regexp}\\z")
  else
    host == pattern
  end
end