1   
  2   
  3   
  4   
  5   
  6   
  7   
  8   
  9   
 10   
 11   
 12   
 13   
 14   
 15   
 16   
 17   
 18   
 19  """ 
 20  L{ServerInterface} is an interface to override for server support. 
 21  """ 
 22   
 23  import threading 
 24  from paramiko.common import * 
 25  from paramiko import util 
 26   
 27   
 29      """ 
 30      A query (set of prompts) for a user during interactive authentication. 
 31      """ 
 32       
 33 -    def __init__(self, name='', instructions='', *prompts): 
  34          """ 
 35          Create a new interactive query to send to the client.  The name and 
 36          instructions are optional, but are generally displayed to the end 
 37          user.  A list of prompts may be included, or they may be added via 
 38          the L{add_prompt} method. 
 39           
 40          @param name: name of this query 
 41          @type name: str 
 42          @param instructions: user instructions (usually short) about this query 
 43          @type instructions: str 
 44          @param prompts: one or more authentication prompts 
 45          @type prompts: str 
 46          """ 
 47          self.name = name 
 48          self.instructions = instructions 
 49          self.prompts = [] 
 50          for x in prompts: 
 51              if (type(x) is str) or (type(x) is unicode): 
 52                  self.add_prompt(x) 
 53              else: 
 54                  self.add_prompt(x[0], x[1]) 
  55       
 57          """ 
 58          Add a prompt to this query.  The prompt should be a (reasonably short) 
 59          string.  Multiple prompts can be added to the same query. 
 60           
 61          @param prompt: the user prompt 
 62          @type prompt: str 
 63          @param echo: C{True} (default) if the user's response should be echoed; 
 64              C{False} if not (for a password or similar) 
 65          @type echo: bool 
 66          """ 
 67          self.prompts.append((prompt, echo)) 
   68   
 69   
 71      """ 
 72      This class defines an interface for controlling the behavior of paramiko 
 73      in server mode. 
 74   
 75      Methods on this class are called from paramiko's primary thread, so you 
 76      shouldn't do too much work in them.  (Certainly nothing that blocks or 
 77      sleeps.) 
 78      """ 
 79   
 81          """ 
 82          Determine if a channel request of a given type will be granted, and 
 83          return C{OPEN_SUCCEEDED} or an error code.  This method is 
 84          called in server mode when the client requests a channel, after 
 85          authentication is complete. 
 86   
 87          If you allow channel requests (and an ssh server that didn't would be 
 88          useless), you should also override some of the channel request methods 
 89          below, which are used to determine which services will be allowed on 
 90          a given channel: 
 91              - L{check_channel_pty_request} 
 92              - L{check_channel_shell_request} 
 93              - L{check_channel_subsystem_request} 
 94              - L{check_channel_window_change_request} 
 95              - L{check_channel_x11_request} 
 96   
 97          The C{chanid} parameter is a small number that uniquely identifies the 
 98          channel within a L{Transport}.  A L{Channel} object is not created 
 99          unless this method returns C{OPEN_SUCCEEDED} -- once a 
100          L{Channel} object is created, you can call L{Channel.get_id} to 
101          retrieve the channel ID. 
102   
103          The return value should either be C{OPEN_SUCCEEDED} (or 
104          C{0}) to allow the channel request, or one of the following error 
105          codes to reject it: 
106              - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED} 
107              - C{OPEN_FAILED_CONNECT_FAILED} 
108              - C{OPEN_FAILED_UNKNOWN_CHANNEL_TYPE} 
109              - C{OPEN_FAILED_RESOURCE_SHORTAGE} 
110           
111          The default implementation always returns 
112          C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED}. 
113   
114          @param kind: the kind of channel the client would like to open 
115              (usually C{"session"}). 
116          @type kind: str 
117          @param chanid: ID of the channel 
118          @type chanid: int 
119          @return: a success or failure code (listed above) 
120          @rtype: int 
121          """ 
122          return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED 
 123   
125          """ 
126          Return a list of authentication methods supported by the server. 
127          This list is sent to clients attempting to authenticate, to inform them 
128          of authentication methods that might be successful. 
129   
130          The "list" is actually a string of comma-separated names of types of 
131          authentication.  Possible values are C{"password"}, C{"publickey"}, 
132          and C{"none"}. 
133   
134          The default implementation always returns C{"password"}. 
135   
136          @param username: the username requesting authentication. 
137          @type username: str 
138          @return: a comma-separated list of authentication types 
139          @rtype: str 
140          """ 
141          return 'password' 
 142   
144          """ 
145          Determine if a client may open channels with no (further) 
146          authentication. 
147   
148          Return L{AUTH_FAILED} if the client must authenticate, or 
149          L{AUTH_SUCCESSFUL} if it's okay for the client to not 
150          authenticate. 
151   
152          The default implementation always returns L{AUTH_FAILED}. 
153   
154          @param username: the username of the client. 
155          @type username: str 
156          @return: L{AUTH_FAILED} if the authentication fails; 
157              L{AUTH_SUCCESSFUL} if it succeeds. 
158          @rtype: int 
159          """ 
160          return AUTH_FAILED 
 161   
163          """ 
164          Determine if a given username and password supplied by the client is 
165          acceptable for use in authentication. 
166   
167          Return L{AUTH_FAILED} if the password is not accepted, 
168          L{AUTH_SUCCESSFUL} if the password is accepted and completes 
169          the authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your 
170          authentication is stateful, and this key is accepted for 
171          authentication, but more authentication is required.  (In this latter 
172          case, L{get_allowed_auths} will be called to report to the client what 
173          options it has for continuing the authentication.) 
174   
175          The default implementation always returns L{AUTH_FAILED}. 
176   
177          @param username: the username of the authenticating client. 
178          @type username: str 
179          @param password: the password given by the client. 
180          @type password: str 
181          @return: L{AUTH_FAILED} if the authentication fails; 
182              L{AUTH_SUCCESSFUL} if it succeeds; 
183              L{AUTH_PARTIALLY_SUCCESSFUL} if the password auth is 
184              successful, but authentication must continue. 
185          @rtype: int 
186          """ 
187          return AUTH_FAILED 
 188   
190          """ 
191          Determine if a given key supplied by the client is acceptable for use 
192          in authentication.  You should override this method in server mode to 
193          check the username and key and decide if you would accept a signature 
194          made using this key. 
195   
196          Return L{AUTH_FAILED} if the key is not accepted, 
197          L{AUTH_SUCCESSFUL} if the key is accepted and completes the 
198          authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your 
199          authentication is stateful, and this password is accepted for 
200          authentication, but more authentication is required.  (In this latter 
201          case, L{get_allowed_auths} will be called to report to the client what 
202          options it has for continuing the authentication.) 
203   
204          Note that you don't have to actually verify any key signtature here. 
205          If you're willing to accept the key, paramiko will do the work of 
206          verifying the client's signature. 
207           
208          The default implementation always returns L{AUTH_FAILED}. 
209   
210          @param username: the username of the authenticating client 
211          @type username: str 
212          @param key: the key object provided by the client 
213          @type key: L{PKey <pkey.PKey>} 
214          @return: L{AUTH_FAILED} if the client can't authenticate 
215              with this key; L{AUTH_SUCCESSFUL} if it can; 
216              L{AUTH_PARTIALLY_SUCCESSFUL} if it can authenticate with 
217              this key but must continue with authentication 
218          @rtype: int 
219          """ 
220          return AUTH_FAILED 
 221       
223          """ 
224          Begin an interactive authentication challenge, if supported.  You 
225          should override this method in server mode if you want to support the 
226          C{"keyboard-interactive"} auth type, which requires you to send a 
227          series of questions for the client to answer. 
228           
229          Return L{AUTH_FAILED} if this auth method isn't supported.  Otherwise, 
230          you should return an L{InteractiveQuery} object containing the prompts 
231          and instructions for the user.  The response will be sent via a call 
232          to L{check_auth_interactive_response}. 
233           
234          The default implementation always returns L{AUTH_FAILED}. 
235           
236          @param username: the username of the authenticating client 
237          @type username: str 
238          @param submethods: a comma-separated list of methods preferred by the 
239              client (usually empty) 
240          @type submethods: str 
241          @return: L{AUTH_FAILED} if this auth method isn't supported; otherwise 
242              an object containing queries for the user 
243          @rtype: int or L{InteractiveQuery} 
244          """ 
245          return AUTH_FAILED 
 246       
248          """ 
249          Continue or finish an interactive authentication challenge, if 
250          supported.  You should override this method in server mode if you want 
251          to support the C{"keyboard-interactive"} auth type. 
252           
253          Return L{AUTH_FAILED} if the responses are not accepted, 
254          L{AUTH_SUCCESSFUL} if the responses are accepted and complete 
255          the authentication, or L{AUTH_PARTIALLY_SUCCESSFUL} if your 
256          authentication is stateful, and this set of responses is accepted for 
257          authentication, but more authentication is required.  (In this latter 
258          case, L{get_allowed_auths} will be called to report to the client what 
259          options it has for continuing the authentication.) 
260   
261          If you wish to continue interactive authentication with more questions, 
262          you may return an L{InteractiveQuery} object, which should cause the 
263          client to respond with more answers, calling this method again.  This 
264          cycle can continue indefinitely. 
265   
266          The default implementation always returns L{AUTH_FAILED}. 
267   
268          @param responses: list of responses from the client 
269          @type responses: list(str) 
270          @return: L{AUTH_FAILED} if the authentication fails; 
271              L{AUTH_SUCCESSFUL} if it succeeds; 
272              L{AUTH_PARTIALLY_SUCCESSFUL} if the interactive auth is 
273              successful, but authentication must continue; otherwise an object 
274              containing queries for the user 
275          @rtype: int or L{InteractiveQuery} 
276          """ 
277          return AUTH_FAILED 
 278           
280          """ 
281          Handle a request for port forwarding.  The client is asking that 
282          connections to the given address and port be forwarded back across 
283          this ssh connection.  An address of C{"0.0.0.0"} indicates a global 
284          address (any address associated with this server) and a port of C{0} 
285          indicates that no specific port is requested (usually the OS will pick 
286          a port). 
287           
288          The default implementation always returns C{False}, rejecting the 
289          port forwarding request.  If the request is accepted, you should return 
290          the port opened for listening. 
291           
292          @param address: the requested address 
293          @type address: str 
294          @param port: the requested port 
295          @type port: int 
296          @return: the port number that was opened for listening, or C{False} to 
297              reject 
298          @rtype: int 
299          """ 
300          return False 
 301       
303          """ 
304          The client would like to cancel a previous port-forwarding request. 
305          If the given address and port is being forwarded across this ssh 
306          connection, the port should be closed. 
307           
308          @param address: the forwarded address 
309          @type address: str 
310          @param port: the forwarded port 
311          @type port: int 
312          """ 
313          pass 
 314           
316          """ 
317          Handle a global request of the given C{kind}.  This method is called 
318          in server mode and client mode, whenever the remote host makes a global 
319          request.  If there are any arguments to the request, they will be in 
320          C{msg}. 
321   
322          There aren't any useful global requests defined, aside from port 
323          forwarding, so usually this type of request is an extension to the 
324          protocol. 
325   
326          If the request was successful and you would like to return contextual 
327          data to the remote host, return a tuple.  Items in the tuple will be 
328          sent back with the successful result.  (Note that the items in the 
329          tuple can only be strings, ints, longs, or bools.) 
330   
331          The default implementation always returns C{False}, indicating that it 
332          does not support any global requests. 
333           
334          @note: Port forwarding requests are handled separately, in 
335              L{check_port_forward_request}. 
336   
337          @param kind: the kind of global request being made. 
338          @type kind: str 
339          @param msg: any extra arguments to the request. 
340          @type msg: L{Message} 
341          @return: C{True} or a tuple of data if the request was granted; 
342              C{False} otherwise. 
343          @rtype: bool 
344          """ 
345          return False 
 346   
347   
348       
349   
350   
353          """ 
354          Determine if a pseudo-terminal of the given dimensions (usually 
355          requested for shell access) can be provided on the given channel. 
356   
357          The default implementation always returns C{False}. 
358   
359          @param channel: the L{Channel} the pty request arrived on. 
360          @type channel: L{Channel} 
361          @param term: type of terminal requested (for example, C{"vt100"}). 
362          @type term: str 
363          @param width: width of screen in characters. 
364          @type width: int 
365          @param height: height of screen in characters. 
366          @type height: int 
367          @param pixelwidth: width of screen in pixels, if known (may be C{0} if 
368              unknown). 
369          @type pixelwidth: int 
370          @param pixelheight: height of screen in pixels, if known (may be C{0} 
371              if unknown). 
372          @type pixelheight: int 
373          @return: C{True} if the psuedo-terminal has been allocated; C{False} 
374              otherwise. 
375          @rtype: bool 
376          """ 
377          return False 
 378   
380          """ 
381          Determine if a shell will be provided to the client on the given 
382          channel.  If this method returns C{True}, the channel should be 
383          connected to the stdin/stdout of a shell (or something that acts like 
384          a shell). 
385   
386          The default implementation always returns C{False}. 
387   
388          @param channel: the L{Channel} the request arrived on. 
389          @type channel: L{Channel} 
390          @return: C{True} if this channel is now hooked up to a shell; C{False} 
391              if a shell can't or won't be provided. 
392          @rtype: bool 
393          """ 
394          return False 
 395   
397          """ 
398          Determine if a shell command will be executed for the client.  If this 
399          method returns C{True}, the channel should be connected to the stdin, 
400          stdout, and stderr of the shell command. 
401           
402          The default implementation always returns C{False}. 
403           
404          @param channel: the L{Channel} the request arrived on. 
405          @type channel: L{Channel} 
406          @param command: the command to execute. 
407          @type command: str 
408          @return: C{True} if this channel is now hooked up to the stdin, 
409              stdout, and stderr of the executing command; C{False} if the 
410              command will not be executed. 
411          @rtype: bool 
412           
413          @since: 1.1 
414          """ 
415          return False 
 416           
418          """ 
419          Determine if a requested subsystem will be provided to the client on 
420          the given channel.  If this method returns C{True}, all future I/O 
421          through this channel will be assumed to be connected to the requested 
422          subsystem.  An example of a subsystem is C{sftp}. 
423   
424          The default implementation checks for a subsystem handler assigned via 
425          L{Transport.set_subsystem_handler}. 
426          If one has been set, the handler is invoked and this method returns 
427          C{True}.  Otherwise it returns C{False}. 
428   
429          @note: Because the default implementation uses the L{Transport} to 
430              identify valid subsystems, you probably won't need to override this 
431              method. 
432   
433          @param channel: the L{Channel} the pty request arrived on. 
434          @type channel: L{Channel} 
435          @param name: name of the requested subsystem. 
436          @type name: str 
437          @return: C{True} if this channel is now hooked up to the requested 
438              subsystem; C{False} if that subsystem can't or won't be provided. 
439          @rtype: bool 
440          """ 
441          handler_class, larg, kwarg = channel.get_transport()._get_subsystem_handler(name) 
442          if handler_class is None: 
443              return False 
444          handler = handler_class(channel, name, self, *larg, **kwarg) 
445          handler.start() 
446          return True 
 447   
449          """ 
450          Determine if the pseudo-terminal on the given channel can be resized. 
451          This only makes sense if a pty was previously allocated on it. 
452   
453          The default implementation always returns C{False}. 
454   
455          @param channel: the L{Channel} the pty request arrived on. 
456          @type channel: L{Channel} 
457          @param width: width of screen in characters. 
458          @type width: int 
459          @param height: height of screen in characters. 
460          @type height: int 
461          @param pixelwidth: width of screen in pixels, if known (may be C{0} if 
462              unknown). 
463          @type pixelwidth: int 
464          @param pixelheight: height of screen in pixels, if known (may be C{0} 
465              if unknown). 
466          @type pixelheight: int 
467          @return: C{True} if the terminal was resized; C{False} if not. 
468          @rtype: bool 
469          """ 
470          return False 
 471       
473          """ 
474          Determine if the client will be provided with an X11 session.  If this 
475          method returns C{True}, X11 applications should be routed through new 
476          SSH channels, using L{Transport.open_x11_channel}. 
477           
478          The default implementation always returns C{False}. 
479           
480          @param channel: the L{Channel} the X11 request arrived on 
481          @type channel: L{Channel} 
482          @param single_connection: C{True} if only a single X11 channel should 
483              be opened 
484          @type single_connection: bool 
485          @param auth_protocol: the protocol used for X11 authentication 
486          @type auth_protocol: str 
487          @param auth_cookie: the cookie used to authenticate to X11 
488          @type auth_cookie: str 
489          @param screen_number: the number of the X11 screen to connect to 
490          @type screen_number: int 
491          @return: C{True} if the X11 session was opened; C{False} if not 
492          @rtype: bool 
493          """ 
494          return False 
 495       
497          """ 
498          Determine if a local port forwarding channel will be granted, and 
499          return C{OPEN_SUCCEEDED} or an error code.  This method is 
500          called in server mode when the client requests a channel, after 
501          authentication is complete. 
502   
503          The C{chanid} parameter is a small number that uniquely identifies the 
504          channel within a L{Transport}.  A L{Channel} object is not created 
505          unless this method returns C{OPEN_SUCCEEDED} -- once a 
506          L{Channel} object is created, you can call L{Channel.get_id} to 
507          retrieve the channel ID. 
508   
509          The origin and destination parameters are (ip_address, port) tuples 
510          that correspond to both ends of the TCP connection in the forwarding 
511          tunnel. 
512   
513          The return value should either be C{OPEN_SUCCEEDED} (or 
514          C{0}) to allow the channel request, or one of the following error 
515          codes to reject it: 
516              - C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED} 
517              - C{OPEN_FAILED_CONNECT_FAILED} 
518              - C{OPEN_FAILED_UNKNOWN_CHANNEL_TYPE} 
519              - C{OPEN_FAILED_RESOURCE_SHORTAGE} 
520           
521          The default implementation always returns 
522          C{OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED}. 
523   
524          @param chanid: ID of the channel 
525          @type chanid: int 
526          @param origin: 2-tuple containing the IP address and port of the 
527              originator (client side) 
528          @type origin: tuple 
529          @param destination: 2-tuple containing the IP address and port of the 
530              destination (server side) 
531          @type destination: tuple 
532          @return: a success or failure code (listed above) 
533          @rtype: int 
534          """ 
535          return OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED 
  536   
537   
539      """ 
540      Handler for a subsytem in server mode.  If you create a subclass of this 
541      class and pass it to 
542      L{Transport.set_subsystem_handler}, 
543      an object of this 
544      class will be created for each request for this subsystem.  Each new object 
545      will be executed within its own new thread by calling L{start_subsystem}. 
546      When that method completes, the channel is closed. 
547   
548      For example, if you made a subclass C{MP3Handler} and registered it as the 
549      handler for subsystem C{"mp3"}, then whenever a client has successfully 
550      authenticated and requests subsytem C{"mp3"}, an object of class 
551      C{MP3Handler} will be created, and L{start_subsystem} will be called on 
552      it from a new thread. 
553      """ 
554 -    def __init__(self, channel, name, server): 
 555          """ 
556          Create a new handler for a channel.  This is used by L{ServerInterface} 
557          to start up a new handler when a channel requests this subsystem.  You 
558          don't need to override this method, but if you do, be sure to pass the 
559          C{channel} and C{name} parameters through to the original C{__init__} 
560          method here. 
561   
562          @param channel: the channel associated with this subsystem request. 
563          @type channel: L{Channel} 
564          @param name: name of the requested subsystem. 
565          @type name: str 
566          @param server: the server object for the session that started this 
567              subsystem 
568          @type server: L{ServerInterface} 
569          """ 
570          threading.Thread.__init__(self, target=self._run) 
571          self.__channel = channel 
572          self.__transport = channel.get_transport() 
573          self.__name = name 
574          self.__server = server 
 575           
577          """ 
578          Return the L{ServerInterface} object associated with this channel and 
579          subsystem. 
580           
581          @rtype: L{ServerInterface} 
582          """ 
583          return self.__server 
 584   
586          try: 
587              self.__transport._log(DEBUG, 'Starting handler for subsystem %s' % self.__name) 
588              self.start_subsystem(self.__name, self.__transport, self.__channel) 
589          except Exception, e: 
590              self.__transport._log(ERROR, 'Exception in subsystem handler for "%s": %s' % 
591                                    (self.__name, str(e))) 
592              self.__transport._log(ERROR, util.tb_strings()) 
593          try: 
594              self.finish_subsystem() 
595          except: 
596              pass 
 597   
599          """ 
600          Process an ssh subsystem in server mode.  This method is called on a 
601          new object (and in a new thread) for each subsystem request.  It is 
602          assumed that all subsystem logic will take place here, and when the 
603          subsystem is finished, this method will return.  After this method 
604          returns, the channel is closed. 
605   
606          The combination of C{transport} and C{channel} are unique; this handler 
607          corresponds to exactly one L{Channel} on one L{Transport}. 
608   
609          @note: It is the responsibility of this method to exit if the 
610              underlying L{Transport} is closed.  This can be done by checking 
611              L{Transport.is_active} or noticing an EOF 
612              on the L{Channel}.  If this method loops forever without checking 
613              for this case, your python interpreter may refuse to exit because 
614              this thread will still be running. 
615   
616          @param name: name of the requested subsystem. 
617          @type name: str 
618          @param transport: the server-mode L{Transport}. 
619          @type transport: L{Transport} 
620          @param channel: the channel associated with this subsystem request. 
621          @type channel: L{Channel} 
622          """ 
623          pass 
 624   
626          """ 
627          Perform any cleanup at the end of a subsystem.  The default 
628          implementation just closes the channel. 
629   
630          @since: 1.1 
631          """ 
632          self.__channel.close() 
  633