Class Net::SSH::Authentication::KeyManager
In: lib/net/ssh/authentication/key_manager.rb
lib/net/ssh/authentication/key_manager.rb
Parent: Object

This class encapsulates all operations done by clients on a user‘s private keys. In practice, the client should never need a reference to a private key; instead, they grab a list of "identities" (public keys) that are available from the KeyManager, and then use the KeyManager to do various private key operations using those identities.

The KeyManager also uses the Agent class to encapsulate the ssh-agent. Thus, from a client‘s perspective it is completely hidden whether an identity comes from the ssh-agent or from a file on disk.

Methods

add   add   agent   agent   clear!   clear!   finish   finish   identities   identities   new   new   sign   sign   use_agent=   use_agent=   use_agent?   use_agent?  

Included Modules

Loggable Loggable

Attributes

key_files  [R]  The list of user key files that will be examined
key_files  [R]  The list of user key files that will be examined
known_identities  [R]  The map of loaded identities
known_identities  [R]  The map of loaded identities
options  [R]  The map of options that were passed to the key-manager
options  [R]  The map of options that were passed to the key-manager

Public Class methods

Create a new KeyManager. By default, the manager will use the ssh-agent (if it is running).

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 38
38:         def initialize(logger, options={})
39:           self.logger = logger
40:           @key_files = []
41:           @use_agent = true
42:           @known_identities = {}
43:           @agent = nil
44:           @options = options
45:         end

Create a new KeyManager. By default, the manager will use the ssh-agent (if it is running).

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 38
38:         def initialize(logger, options={})
39:           self.logger = logger
40:           @key_files = []
41:           @use_agent = true
42:           @known_identities = {}
43:           @agent = nil
44:           @options = options
45:         end

Public Instance methods

Add the given key_file to the list of key files that will be used.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 58
58:         def add(key_file)
59:           key_files.push(File.expand_path(key_file)).uniq!
60:           self
61:         end

Add the given key_file to the list of key files that will be used.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 58
58:         def add(key_file)
59:           key_files.push(File.expand_path(key_file)).uniq!
60:           self
61:         end

Returns an Agent instance to use for communicating with an SSH agent process. Returns nil if use of an SSH agent has been disabled, or if the agent is otherwise not available.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 156
156:         def agent
157:           return unless use_agent?
158:           @agent ||= Agent.connect(logger)
159:         rescue AgentNotAvailable
160:           @use_agent = false
161:           nil
162:         end

Returns an Agent instance to use for communicating with an SSH agent process. Returns nil if use of an SSH agent has been disabled, or if the agent is otherwise not available.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 156
156:         def agent
157:           return unless use_agent?
158:           @agent ||= Agent.connect(logger)
159:         rescue AgentNotAvailable
160:           @use_agent = false
161:           nil
162:         end

Clear all knowledge of any loaded user keys. This also clears the list of default identity files that are to be loaded, thus making it appropriate to use if a client wishes to NOT use the default identity files.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 51
51:         def clear!
52:           key_files.clear
53:           known_identities.clear
54:           self
55:         end

Clear all knowledge of any loaded user keys. This also clears the list of default identity files that are to be loaded, thus making it appropriate to use if a client wishes to NOT use the default identity files.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 51
51:         def clear!
52:           key_files.clear
53:           known_identities.clear
54:           self
55:         end

This is used as a hint to the KeyManager indicating that the agent connection is no longer needed. Any other open resources may be closed at this time.

Calling this does NOT indicate that the KeyManager will no longer be used. Identities may still be requested and operations done on loaded identities, in which case, the agent will be automatically reconnected. This method simply allows the client connection to be closed when it will not be used in the immediate future.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 72
72:         def finish
73:           @agent.close if @agent
74:           @agent = nil
75:         end

This is used as a hint to the KeyManager indicating that the agent connection is no longer needed. Any other open resources may be closed at this time.

Calling this does NOT indicate that the KeyManager will no longer be used. Identities may still be requested and operations done on loaded identities, in which case, the agent will be automatically reconnected. This method simply allows the client connection to be closed when it will not be used in the immediate future.

[Source]

    # File lib/net/ssh/authentication/key_manager.rb, line 72
72:         def finish
73:           @agent.close if @agent
74:           @agent = nil
75:         end

Returns an array of identities (public keys) known to this manager. The origin of the identities may be from files on disk or from an ssh-agent. Note that identities from an ssh-agent are always listed first in the array, with other identities coming after.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 81
 81:         def identities
 82:           identities = []
 83: 
 84:           if agent
 85:             agent.identities.each do |key|
 86:               identities.push key
 87:               known_identities[key] = { :from => :agent }
 88:             end
 89:           end
 90: 
 91:           key_files.each do |file|
 92:             public_key_file = file + '.pub'
 93:             if File.readable?(public_key_file)
 94:               begin
 95:                 key = KeyFactory.load_public_key(public_key_file)
 96:                 identities.push key
 97:                 known_identities[key] = { :from => :file, :file => file }
 98:               rescue Exception => e
 99:                 error { "could not load public key file `#{file}.pub': #{e.class} (#{e.message})" }
100:               end
101:             end
102:           end
103: 
104:           identities
105:         end

Returns an array of identities (public keys) known to this manager. The origin of the identities may be from files on disk or from an ssh-agent. Note that identities from an ssh-agent are always listed first in the array, with other identities coming after.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 81
 81:         def identities
 82:           identities = []
 83: 
 84:           if agent
 85:             agent.identities.each do |key|
 86:               identities.push key
 87:               known_identities[key] = { :from => :agent }
 88:             end
 89:           end
 90: 
 91:           key_files.each do |file|
 92:             public_key_file = file + '.pub'
 93:             if File.readable?(public_key_file)
 94:               begin
 95:                 key = KeyFactory.load_public_key(public_key_file)
 96:                 identities.push key
 97:                 known_identities[key] = { :from => :file, :file => file }
 98:               rescue Exception => e
 99:                 error { "could not load public key file `#{file}.pub': #{e.class} (#{e.message})" }
100:               end
101:             end
102:           end
103: 
104:           identities
105:         end

Sign the given data, using the corresponding private key of the given identity. If the identity was originally obtained from an ssh-agent, then the ssh-agent will be used to sign the data, otherwise the private key for the identity will be loaded from disk (if it hasn‘t been loaded already) and will then be used to sign the data.

Regardless of the identity‘s origin or who does the signing, this will always return the signature in an SSH2-specified "signature blob" format.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 116
116:         def sign(identity, data)
117:           info = known_identities[identity] or raise KeyManagerError, "the given identity is unknown to the key manager"
118: 
119:           if info[:key].nil? && info[:from] == :file
120:             begin
121:               info[:key] = KeyFactory.load_private_key(info[:file], options[:passphrase])
122:             rescue Exception => e 
123:               raise KeyManagerError, "the given identity is known, but the private key could not be loaded: #{e.class} (#{e.message})"
124:             end
125:           end
126: 
127:           if info[:key]
128:             return Net::SSH::Buffer.from(:string, identity.ssh_type,
129:               :string, info[:key].ssh_do_sign(data.to_s)).to_s
130:           end
131: 
132:           if info[:from] == :agent
133:             raise KeyManagerError, "the agent is no longer available" unless agent
134:             return agent.sign(identity, data.to_s)
135:           end
136: 
137:           raise KeyManagerError, "[BUG] can't determine identity origin (#{info.inspect})"
138:         end

Sign the given data, using the corresponding private key of the given identity. If the identity was originally obtained from an ssh-agent, then the ssh-agent will be used to sign the data, otherwise the private key for the identity will be loaded from disk (if it hasn‘t been loaded already) and will then be used to sign the data.

Regardless of the identity‘s origin or who does the signing, this will always return the signature in an SSH2-specified "signature blob" format.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 116
116:         def sign(identity, data)
117:           info = known_identities[identity] or raise KeyManagerError, "the given identity is unknown to the key manager"
118: 
119:           if info[:key].nil? && info[:from] == :file
120:             begin
121:               info[:key] = KeyFactory.load_private_key(info[:file], options[:passphrase])
122:             rescue Exception => e 
123:               raise KeyManagerError, "the given identity is known, but the private key could not be loaded: #{e.class} (#{e.message})"
124:             end
125:           end
126: 
127:           if info[:key]
128:             return Net::SSH::Buffer.from(:string, identity.ssh_type,
129:               :string, info[:key].ssh_do_sign(data.to_s)).to_s
130:           end
131: 
132:           if info[:from] == :agent
133:             raise KeyManagerError, "the agent is no longer available" unless agent
134:             return agent.sign(identity, data.to_s)
135:           end
136: 
137:           raise KeyManagerError, "[BUG] can't determine identity origin (#{info.inspect})"
138:         end

Toggles whether the ssh-agent will be used or not. If true, an attempt will be made to use the ssh-agent. If false, any existing connection to an agent is closed and the agent will not be used.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 148
148:         def use_agent=(use_agent)
149:           finish if !use_agent
150:           @use_agent = use_agent
151:         end

Toggles whether the ssh-agent will be used or not. If true, an attempt will be made to use the ssh-agent. If false, any existing connection to an agent is closed and the agent will not be used.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 148
148:         def use_agent=(use_agent)
149:           finish if !use_agent
150:           @use_agent = use_agent
151:         end

Identifies whether the ssh-agent will be used or not.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 141
141:         def use_agent?
142:           @use_agent
143:         end

Identifies whether the ssh-agent will be used or not.

[Source]

     # File lib/net/ssh/authentication/key_manager.rb, line 141
141:         def use_agent?
142:           @use_agent
143:         end

[Validate]