Object
Implements the higher-level logic behind an SSH key-exchange. It handles both the initial exchange, as well as subsequent re-exchanges (as needed). It also encapsulates the negotiation of the algorithms, and provides a single point of access to the negotiated algorithms.
You will never instantiate or reference this directly. It is used internally by the transport layer.
Define the default algorithms, in order of preference, supported by Net::SSH.
The type of the cipher to use to encrypt packets sent from the client to the server.
The type of compression to use to decompress packets arriving from the server.
Returns true if the given packet can be processed during a key-exchange.
# File lib/net/ssh/transport/algorithms.rb, line 105 105: def self.allowed_packet?(packet) 106: ( 1.. 4).include?(packet.type) || 107: ( 6..19).include?(packet.type) || 108: (21..49).include?(packet.type) 109: end
Instantiates a new Algorithms object, and prepares the hash of preferred algorithms based on the options parameter and the ALGORITHMS constant.
# File lib/net/ssh/transport/algorithms.rb, line 113 113: def initialize(session, options={}) 114: @session = session 115: @logger = session.logger 116: @options = options 117: @algorithms = {} 118: @pending = @initialized = false 119: @client_packet = @server_packet = nil 120: prepare_preferred_algorithms! 121: end
A convenience method for accessing the list of preferred types for a specific algorithm (see #).
# File lib/net/ssh/transport/algorithms.rb, line 150 150: def [](key) 151: algorithms[key] 152: end
Called by the transport layer when a KEXINIT packet is recieved, indicating that the server wants to exchange keys. This can be spontaneous, or it can be in response to a client-initiated rekey request (see #). Either way, this will block until the key exchange completes.
# File lib/net/ssh/transport/algorithms.rb, line 137 137: def accept_kexinit(packet) 138: info { "got KEXINIT from server" } 139: @server_data = parse_server_algorithm_packet(packet) 140: @server_packet = @server_data[:raw] 141: if !pending? 142: send_kexinit 143: else 144: proceed! 145: end 146: end
Returns true if no exchange is pending, and otherwise returns true or false depending on whether the given packet is of a type that is allowed during a key exchange.
# File lib/net/ssh/transport/algorithms.rb, line 166 166: def allow?(packet) 167: !pending? || Algorithms.allowed_packet?(packet) 168: end
Returns true if the algorithms have been negotiated at all.
# File lib/net/ssh/transport/algorithms.rb, line 171 171: def initialized? 172: @initialized 173: end
Returns true if a key-exchange is pending. This will be true from the moment either the client or server requests the key exchange, until the exchange completes. While an exchange is pending, only a limited number of packets are allowed, so event processing essentially stops during this period.
# File lib/net/ssh/transport/algorithms.rb, line 159 159: def pending? 160: @pending 161: end
Request a rekey operation. This will return immediately, and does not actually perform the rekey operation. It does cause the session to change state, however—until the key exchange finishes, no new packets will be processed.
# File lib/net/ssh/transport/algorithms.rb, line 127 127: def rekey! 128: @client_packet = @server_packet = nil 129: @initialized = false 130: send_kexinit 131: end
Given the # map of preferred algorithm types, this constructs a KEXINIT packet to send to the server. It does not actually send it, it simply builds the packet and returns it.
# File lib/net/ssh/transport/algorithms.rb, line 274 274: def build_client_algorithm_packet 275: kex = algorithms[:kex ].join(",") 276: host_key = algorithms[:host_key ].join(",") 277: encryption = algorithms[:encryption ].join(",") 278: hmac = algorithms[:hmac ].join(",") 279: compression = algorithms[:compression].join(",") 280: language = algorithms[:language ].join(",") 281: 282: Net::SSH::Buffer.from(:byte, KEXINIT, 283: :long, [rand(0xFFFFFFFF), rand(0xFFFFFFFF), rand(0xFFFFFFFF), rand(0xFFFFFFFF)], 284: :string, [kex, host_key, encryption, encryption, hmac, hmac], 285: :string, [compression, compression, language, language], 286: :bool, false, :long, 0) 287: end
Instantiates one of the Transport::Kex classes (based on the negotiated kex algorithm), and uses it to exchange keys. Then, the ciphers and HMACs are initialized and fed to the transport layer, to be used in further communication with the server.
# File lib/net/ssh/transport/algorithms.rb, line 345 345: def exchange_keys 346: debug { "exchanging keys" } 347: 348: algorithm = Kex::MAP[kex].new(self, session, 349: :client_version_string => Net::SSH::Transport::ServerVersion::PROTO_VERSION, 350: :server_version_string => session.server_version.version, 351: :server_algorithm_packet => @server_packet, 352: :client_algorithm_packet => @client_packet, 353: :need_bytes => kex_byte_requirement, 354: :logger => logger) 355: result = algorithm.exchange_keys 356: 357: secret = result[:shared_secret].to_ssh 358: hash = result[:session_id] 359: digester = result[:hashing_algorithm] 360: 361: @session_id ||= hash 362: 363: key = Proc.new { |salt| digester.digest(secret + hash + salt + @session_id) } 364: 365: iv_client = key["A"] 366: iv_server = key["B"] 367: key_client = key["C"] 368: key_server = key["D"] 369: mac_key_client = key["E"] 370: mac_key_server = key["F"] 371: 372: parameters = { :shared => secret, :hash => hash, :digester => digester } 373: 374: cipher_client = CipherFactory.get(encryption_client, parameters.merge(:iv => iv_client, :key => key_client, :encrypt => true)) 375: cipher_server = CipherFactory.get(encryption_server, parameters.merge(:iv => iv_server, :key => key_server, :decrypt => true)) 376: 377: mac_client = HMAC.get(hmac_client, mac_key_client, parameters) 378: mac_server = HMAC.get(hmac_server, mac_key_server, parameters) 379: 380: session.configure_client :cipher => cipher_client, :hmac => mac_client, 381: :compression => normalize_compression_name(compression_client), 382: :compression_level => options[:compression_level], 383: :rekey_limit => options[:rekey_limit], 384: :max_packets => options[:rekey_packet_limit], 385: :max_blocks => options[:rekey_blocks_limit] 386: 387: session.configure_server :cipher => cipher_server, :hmac => mac_server, 388: :compression => normalize_compression_name(compression_server), 389: :rekey_limit => options[:rekey_limit], 390: :max_packets => options[:rekey_packet_limit], 391: :max_blocks => options[:rekey_blocks_limit] 392: 393: @initialized = true 394: end
Considers the sizes of the keys and block-sizes for the selected ciphers, and the lengths of the hmacs, and returns the largest as the byte requirement for the key-exchange algorithm.
# File lib/net/ssh/transport/algorithms.rb, line 329 329: def kex_byte_requirement 330: sizes = [8] # require at least 8 bytes 331: 332: sizes.concat(CipherFactory.get_lengths(encryption_client)) 333: sizes.concat(CipherFactory.get_lengths(encryption_server)) 334: 335: sizes << HMAC.key_length(hmac_client) 336: sizes << HMAC.key_length(hmac_server) 337: 338: sizes.max 339: end
Negotiates a single algorithm based on the preferences reported by the server and those set by the client. This is called by #.
# File lib/net/ssh/transport/algorithms.rb, line 316 316: def negotiate(algorithm) 317: match = self[algorithm].find { |item| @server_data[algorithm].include?(item) } 318: 319: if match.nil? 320: raise Net::SSH::Exception, "could not settle on #{algorithm} algorithm" 321: end 322: 323: return match 324: end
Given the parsed server KEX packet, and the client’s preferred algorithm lists in #, determine which preferred algorithms each has in common and set those as the selected algorithms. If, for any algorithm, no type can be settled on, an exception is raised.
# File lib/net/ssh/transport/algorithms.rb, line 293 293: def negotiate_algorithms 294: @kex = negotiate(:kex) 295: @host_key = negotiate(:host_key) 296: @encryption_client = negotiate(:encryption_client) 297: @encryption_server = negotiate(:encryption_server) 298: @hmac_client = negotiate(:hmac_client) 299: @hmac_server = negotiate(:hmac_server) 300: @compression_client = negotiate(:compression_client) 301: @compression_server = negotiate(:compression_server) 302: @language_client = negotiate(:language_client) rescue "" 303: @language_server = negotiate(:language_server) rescue "" 304: 305: debug do 306: "negotiated:\n" + 307: [:kex, :host_key, :encryption_server, :encryption_client, :hmac_client, :hmac_server, :compression_client, :compression_server, :language_client, :language_server].map do |key| 308: "* #{key}: #{instance_variable_get("@#{key}")}" 309: end.join("\n") 310: end 311: end
Given the SSH name for some compression algorithm, return a normalized name as a symbol.
# File lib/net/ssh/transport/algorithms.rb, line 398 398: def normalize_compression_name(name) 399: case name 400: when "none" then false 401: when "zlib" then :standard 402: when "zlib@openssh.com" then :delayed 403: else raise ArgumentError, "unknown compression type `#{name}'" 404: end 405: end
Parses a KEXINIT packet from the server.
# File lib/net/ssh/transport/algorithms.rb, line 247 247: def parse_server_algorithm_packet(packet) 248: data = { :raw => packet.content } 249: 250: packet.read(16) # skip the cookie value 251: 252: data[:kex] = packet.read_string.split(/,/) 253: data[:host_key] = packet.read_string.split(/,/) 254: data[:encryption_client] = packet.read_string.split(/,/) 255: data[:encryption_server] = packet.read_string.split(/,/) 256: data[:hmac_client] = packet.read_string.split(/,/) 257: data[:hmac_server] = packet.read_string.split(/,/) 258: data[:compression_client] = packet.read_string.split(/,/) 259: data[:compression_server] = packet.read_string.split(/,/) 260: data[:language_client] = packet.read_string.split(/,/) 261: data[:language_server] = packet.read_string.split(/,/) 262: 263: # TODO: if first_kex_packet_follows, we need to try to skip the 264: # actual kexinit stuff and try to guess what the server is doing... 265: # need to read more about this scenario. 266: first_kex_packet_follows = packet.read_bool 267: 268: return data 269: end
Prepares the list of preferred algorithms, based on the options hash that was given when the object was constructed, and the ALGORITHMS constant. Also, when determining the host_key type to use, the known hosts files are examined to see if the host has ever sent a host_key before, and if so, that key type is used as the preferred type for communicating with this server.
# File lib/net/ssh/transport/algorithms.rb, line 206 206: def prepare_preferred_algorithms! 207: options[:compression] = %(zlib@openssh.com zlib) if options[:compression] == true 208: 209: ALGORITHMS.each do |algorithm, list| 210: algorithms[algorithm] = list.dup 211: 212: # apply the preferred algorithm order, if any 213: if options[algorithm] 214: algorithms[algorithm] = Array(options[algorithm]).compact.uniq 215: invalid = algorithms[algorithm].detect { |name| !ALGORITHMS[algorithm].include?(name) } 216: raise NotImplementedError, "unsupported #{algorithm} algorithm: `#{invalid}'" if invalid 217: 218: # make sure all of our supported algorithms are tacked onto the 219: # end, so that if the user tries to give a list of which none are 220: # supported, we can still proceed. 221: list.each { |name| algorithms[algorithm] << name unless algorithms[algorithm].include?(name) } 222: end 223: end 224: 225: # for convention, make sure our list has the same keys as the server 226: # list 227: 228: algorithms[:encryption_client ] = algorithms[:encryption_server ] = algorithms[:encryption] 229: algorithms[:hmac_client ] = algorithms[:hmac_server ] = algorithms[:hmac] 230: algorithms[:compression_client] = algorithms[:compression_server] = algorithms[:compression] 231: algorithms[:language_client ] = algorithms[:language_server ] = algorithms[:language] 232: 233: if !options.key?(:host_key) 234: # make sure the host keys are specified in preference order, where any 235: # existing known key for the host has preference. 236: 237: existing_keys = KnownHosts.search_for(options[:host_key_alias] || session.host_as_string, options) 238: host_keys = existing_keys.map { |key| key.ssh_type }.uniq 239: algorithms[:host_key].each do |name| 240: host_keys << name unless host_keys.include?(name) 241: end 242: algorithms[:host_key] = host_keys 243: end 244: end
After both client and server have sent their KEXINIT packets, this will do the algorithm negotiation and key exchange. Once both finish, the object leaves the pending state and the method returns.
# File lib/net/ssh/transport/algorithms.rb, line 193 193: def proceed! 194: info { "negotiating algorithms" } 195: negotiate_algorithms 196: exchange_keys 197: @pending = false 198: end
Sends a KEXINIT packet to the server. If a server KEXINIT has already been received, this will then invoke # to proceed with the key exchange, otherwise it returns immediately (but sets the object to the pending state).
# File lib/net/ssh/transport/algorithms.rb, line 181 181: def send_kexinit 182: info { "sending KEXINIT" } 183: @pending = true 184: packet = build_client_algorithm_packet 185: @client_packet = packet.to_s 186: session.send_message(packet) 187: proceed! if @server_packet 188: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.