Class Net::SSH::UserAuth::UserKeyManager
In: lib/net/ssh/userauth/userkeys.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 UserKeyManager, and then use the UserKeyManager to do various private key operations using those identities.

The UserKeyManager 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

Attributes

agent_factory  [W]  The agent factory to use when a new agent instance is needed.
buffers  [W]  The buffer manager to use for providing new buffer instances.
host_key_files  [R]  The list of host key files that will be examined
key_existence_tester  [W]  The object that will be used to test whether a given key file is readable. This object must only respond to "readable?" with one parameter, the file to test the readability of.
key_files  [R]  The list of user key files that will be examined
keys  [W]  The key manager instance to use for managing keys
log  [W]  The logger instance to use for logging messages

Public Class methods

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

[Source]

    # File lib/net/ssh/userauth/userkeys.rb, line 64
64:         def initialize
65:           @key_files = []
66:           @host_key_files = []
67:           @use_agent = true
68:           @agent = nil
69:         end

Public Instance methods

<<( key_file )

Alias for add

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

[Source]

    # File lib/net/ssh/userauth/userkeys.rb, line 92
92:         def add( key_file )
93:           @key_files.push( key_file ).uniq!
94:           self
95:         end

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

[Source]

     # File lib/net/ssh/userauth/userkeys.rb, line 101
101:         def add_host_key( key_file )
102:           @host_key_files.push( key_file ).uniq!
103:           self
104:         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/userauth/userkeys.rb, line 75
75:         def clear!
76:           @key_files = []
77:           @known_identities = nil
78:           self
79:         end

Clear all knowledge of any loaded host 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/userauth/userkeys.rb, line 85
85:         def clear_host!
86:           @host_key_files = []
87:           @known_host_identities = nil
88:           self
89:         end

This is used as a hint to the UserKeyManager 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 UserKeyManager 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/userauth/userkeys.rb, line 115
115:         def finish
116:           close_agent
117:         end

Returns an array of host identities (public keys) known to this manager. Host identities are those that identify the current host, and are used (typically) for hostbased authentication.

[Source]

     # File lib/net/ssh/userauth/userkeys.rb, line 154
154:         def host_identities
155:           identities = []
156:           @known_host_identities = Hash.new
157: 
158:           @host_key_files.each do |file|
159:             if @key_existence_tester.readable?( file )
160:               begin
161:                 key = @keys.load_public_key( file + ".pub" )
162:                 identities.push key
163:                 @known_host_identities[ key ] =
164:                   { :from => :file, :file => file }
165:               rescue Exception => e
166:                 @log.warn "could not load public host key file " +
167:                   "'#{file}.pub' (#{e.message} [#{e.class}])" if @log.warn?
168:               end
169:             end
170:           end
171: 
172:           identities
173:         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/userauth/userkeys.rb, line 123
123:         def identities
124:           identities = []
125:           @known_identities = Hash.new
126: 
127:           ensure_agent
128:           if @agent
129:             @agent.identities.each do |key|
130:               identities.push key
131:               @known_identities[ key ] = { :from => :agent }
132:             end
133:           end
134: 
135:           @key_files.each do |file|
136:             if @key_existence_tester.readable?( file )
137:               begin
138:                 key = @keys.load_public_key( file + ".pub" )
139:                 identities.push key
140:                 @known_identities[ key ] = { :from => :file, :file => file }
141:               rescue Exception => e
142:                 @log.warn "could not load public key file " +
143:                   "'#{file}.pub' (#{e.message} [#{e.class}])" if @log.warn?
144:               end
145:             end
146:           end
147: 
148:           identities
149:         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/userauth/userkeys.rb, line 184
184:         def sign( identity, data )
185:           info = find_identity( identity )
186: 
187:           if info[:key].nil? && info[:from] == :file
188:             begin
189:               info[:key] = @keys.load_private_key( info[:file] )
190:             rescue Exception => e 
191:               raise UserKeyManagerError,
192:                     "the given identity is known, " +
193:                     "but the private key could not be loaded " +
194:                     "(#{e.message} [#{e.class}])"
195:             end
196:           end
197: 
198:           if info[:key]
199:             sig_blob = @buffers.writer
200:             sig_blob.write_string identity.ssh_type
201:             sig_blob.write_string info[:key].ssh_do_sign( data.to_s )
202:             return sig_blob.to_s
203:           end
204: 
205:           if info[:from] == :agent
206:             raise UserKeyManagerError,
207:               "the agent is no longer available" unless @agent
208:             return @agent.sign( identity, data.to_s )
209:           end
210: 
211:           raise UserKeyManagerError,
212:             "[BUG] can't determine identity origin (#{info.inspect})"
213:         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/userauth/userkeys.rb, line 223
223:         def use_agent=( use_agent )
224:           close_agent if !use_agent
225:           @use_agent = use_agent
226:         end

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

[Source]

     # File lib/net/ssh/userauth/userkeys.rb, line 216
216:         def use_agent?
217:           @use_agent
218:         end

[Validate]