Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

_pop3client.py 46KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235
  1. # -*- test-case-name: twisted.mail.test.test_pop3client -*-
  2. # Copyright (c) 2001-2004 Divmod Inc.
  3. # Copyright (c) Twisted Matrix Laboratories.
  4. # See LICENSE for details.
  5. """
  6. A POP3 client protocol implementation.
  7. Don't use this module directly. Use twisted.mail.pop3 instead.
  8. @author: Jp Calderone
  9. """
  10. import re
  11. from hashlib import md5
  12. from typing import List
  13. from twisted.internet import defer, error, interfaces
  14. from twisted.mail._except import (
  15. InsecureAuthenticationDisallowed,
  16. LineTooLong,
  17. ServerErrorResponse,
  18. TLSError,
  19. TLSNotSupportedError,
  20. )
  21. from twisted.protocols import basic, policies
  22. from twisted.python import log
  23. OK = b"+OK"
  24. ERR = b"-ERR"
  25. class _ListSetter:
  26. """
  27. A utility class to construct a list from a multi-line response accounting
  28. for deleted messages.
  29. POP3 responses sometimes occur in the form of a list of lines containing
  30. two pieces of data, a message index and a value of some sort. When a
  31. message is deleted, it is omitted from these responses. The L{setitem}
  32. method of this class is meant to be called with these two values. In the
  33. cases where indices are skipped, it takes care of padding out the missing
  34. values with L{None}.
  35. @ivar L: See L{__init__}
  36. """
  37. def __init__(self, L):
  38. """
  39. @type L: L{list} of L{object}
  40. @param L: The list being constructed. An empty list should be
  41. passed in.
  42. """
  43. self.L = L
  44. def setitem(self, itemAndValue):
  45. """
  46. Add the value at the specified position, padding out missing entries.
  47. @type itemAndValue: C{tuple}
  48. @param itemAndValue: A tuple of (item, value). The I{item} is the 0-based
  49. index in the list at which the value should be placed. The value is
  50. is an L{object} to put in the list.
  51. """
  52. (item, value) = itemAndValue
  53. diff = item - len(self.L) + 1
  54. if diff > 0:
  55. self.L.extend([None] * diff)
  56. self.L[item] = value
  57. def _statXform(line):
  58. """
  59. Parse the response to a STAT command.
  60. @type line: L{bytes}
  61. @param line: The response from the server to a STAT command minus the
  62. status indicator.
  63. @rtype: 2-L{tuple} of (0) L{int}, (1) L{int}
  64. @return: The number of messages in the mailbox and the size of the mailbox.
  65. """
  66. numMsgs, totalSize = line.split(None, 1)
  67. return int(numMsgs), int(totalSize)
  68. def _listXform(line):
  69. """
  70. Parse a line of the response to a LIST command.
  71. The line from the LIST response consists of a 1-based message number
  72. followed by a size.
  73. @type line: L{bytes}
  74. @param line: A non-initial line from the multi-line response to a LIST
  75. command.
  76. @rtype: 2-L{tuple} of (0) L{int}, (1) L{int}
  77. @return: The 0-based index of the message and the size of the message.
  78. """
  79. index, size = line.split(None, 1)
  80. return int(index) - 1, int(size)
  81. def _uidXform(line):
  82. """
  83. Parse a line of the response to a UIDL command.
  84. The line from the UIDL response consists of a 1-based message number
  85. followed by a unique id.
  86. @type line: L{bytes}
  87. @param line: A non-initial line from the multi-line response to a UIDL
  88. command.
  89. @rtype: 2-L{tuple} of (0) L{int}, (1) L{bytes}
  90. @return: The 0-based index of the message and the unique identifier
  91. for the message.
  92. """
  93. index, uid = line.split(None, 1)
  94. return int(index) - 1, uid
  95. def _codeStatusSplit(line):
  96. """
  97. Parse the first line of a multi-line server response.
  98. @type line: L{bytes}
  99. @param line: The first line of a multi-line server response.
  100. @rtype: 2-tuple of (0) L{bytes}, (1) L{bytes}
  101. @return: The status indicator and the rest of the server response.
  102. """
  103. parts = line.split(b" ", 1)
  104. if len(parts) == 1:
  105. return parts[0], b""
  106. return parts
  107. def _dotUnquoter(line):
  108. """
  109. Remove a byte-stuffed termination character at the beginning of a line if
  110. present.
  111. When the termination character (C{'.'}) appears at the beginning of a line,
  112. the server byte-stuffs it by adding another termination character to
  113. avoid confusion with the terminating sequence (C{'.\\r\\n'}).
  114. @type line: L{bytes}
  115. @param line: A received line.
  116. @rtype: L{bytes}
  117. @return: The line without the byte-stuffed termination character at the
  118. beginning if it was present. Otherwise, the line unchanged.
  119. """
  120. if line.startswith(b".."):
  121. return line[1:]
  122. return line
  123. class POP3Client(basic.LineOnlyReceiver, policies.TimeoutMixin):
  124. """
  125. A POP3 client protocol.
  126. Instances of this class provide a convenient, efficient API for
  127. retrieving and deleting messages from a POP3 server.
  128. This API provides a pipelining interface but POP3 pipelining
  129. on the network is not yet supported.
  130. @type startedTLS: L{bool}
  131. @ivar startedTLS: An indication of whether TLS has been negotiated
  132. successfully.
  133. @type allowInsecureLogin: L{bool}
  134. @ivar allowInsecureLogin: An indication of whether plaintext login should
  135. be allowed when the server offers no authentication challenge and the
  136. transport does not offer any protection via encryption.
  137. @type serverChallenge: L{bytes} or L{None}
  138. @ivar serverChallenge: The challenge received in the server greeting.
  139. @type timeout: L{int}
  140. @ivar timeout: The number of seconds to wait on a response from the server
  141. before timing out a connection. If the number is <= 0, no timeout
  142. checking will be performed.
  143. @type _capCache: L{None} or L{dict} mapping L{bytes}
  144. to L{list} of L{bytes} and/or L{bytes} to L{None}
  145. @ivar _capCache: The cached server capabilities. Capabilities are not
  146. allowed to change during the session (except when TLS is negotiated),
  147. so the first response to a capabilities command can be used for
  148. later lookups.
  149. @type _challengeMagicRe: L{Pattern <re.Pattern.search>}
  150. @ivar _challengeMagicRe: A regular expression which matches the
  151. challenge in the server greeting.
  152. @type _blockedQueue: L{None} or L{list} of 3-L{tuple}
  153. of (0) L{Deferred <defer.Deferred>}, (1) callable which results
  154. in a L{Deferred <defer.Deferred>}, (2) L{tuple}
  155. @ivar _blockedQueue: A list of blocked commands. While a command is
  156. awaiting a response from the server, other commands are blocked. When
  157. no command is outstanding, C{_blockedQueue} is set to L{None}.
  158. Otherwise, it contains a list of information about blocked commands.
  159. Each list entry provides the following information about a blocked
  160. command: the deferred that should be called when the response to the
  161. command is received, the function that sends the command, and the
  162. arguments to the function.
  163. @type _waiting: L{Deferred <defer.Deferred>} or
  164. L{None}
  165. @ivar _waiting: A deferred which fires when the response to the
  166. outstanding command is received from the server.
  167. @type _timedOut: L{bool}
  168. @ivar _timedOut: An indication of whether the connection was dropped
  169. because of a timeout.
  170. @type _greetingError: L{bytes} or L{None}
  171. @ivar _greetingError: The server greeting minus the status indicator, when
  172. the connection was dropped because of an error in the server greeting.
  173. Otherwise, L{None}.
  174. @type state: L{bytes}
  175. @ivar state: The state which indicates what type of response is expected
  176. from the server. Valid states are: 'WELCOME', 'WAITING', 'SHORT',
  177. 'LONG_INITIAL', 'LONG'.
  178. @type _xform: L{None} or callable that takes L{bytes}
  179. and returns L{object}
  180. @ivar _xform: The transform function which is used to convert each
  181. line of a multi-line response into usable values for use by the
  182. consumer function. If L{None}, each line of the multi-line response
  183. is sent directly to the consumer function.
  184. @type _consumer: callable that takes L{object}
  185. @ivar _consumer: The consumer function which is used to store the
  186. values derived by the transform function from each line of a
  187. multi-line response into a list.
  188. """
  189. startedTLS = False
  190. allowInsecureLogin = False
  191. timeout = 0
  192. serverChallenge = None
  193. _capCache = None
  194. _challengeMagicRe = re.compile(b"(<[^>]+>)")
  195. _blockedQueue = None
  196. _waiting = None
  197. _timedOut = False
  198. _greetingError = None
  199. def _blocked(self, f, *a):
  200. """
  201. Block a command, if necessary.
  202. If commands are being blocked, append information about the function
  203. which sends the command to a list and return a deferred that will be
  204. chained with the return value of the function when it eventually runs.
  205. Otherwise, set up for subsequent commands to be blocked and return
  206. L{None}.
  207. @type f: callable
  208. @param f: A function which sends a command.
  209. @type a: L{tuple}
  210. @param a: Arguments to the function.
  211. @rtype: L{None} or L{Deferred <defer.Deferred>}
  212. @return: L{None} if the command can run immediately. Otherwise,
  213. a deferred that will eventually trigger with the return value of
  214. the function.
  215. """
  216. if self._blockedQueue is not None:
  217. d = defer.Deferred()
  218. self._blockedQueue.append((d, f, a))
  219. return d
  220. self._blockedQueue = []
  221. return None
  222. def _unblock(self):
  223. """
  224. Send the next blocked command.
  225. If there are no more commands in the blocked queue, set up for the next
  226. command to be sent immediately.
  227. """
  228. if self._blockedQueue == []:
  229. self._blockedQueue = None
  230. elif self._blockedQueue is not None:
  231. _blockedQueue = self._blockedQueue
  232. self._blockedQueue = None
  233. d, f, a = _blockedQueue.pop(0)
  234. d2 = f(*a)
  235. d2.chainDeferred(d)
  236. # f is a function which uses _blocked (otherwise it wouldn't
  237. # have gotten into the blocked queue), which means it will have
  238. # re-set _blockedQueue to an empty list, so we can put the rest
  239. # of the blocked queue back into it now.
  240. self._blockedQueue.extend(_blockedQueue)
  241. def sendShort(self, cmd, args):
  242. """
  243. Send a POP3 command to which a short response is expected.
  244. Block all further commands from being sent until the response is
  245. received. Transition the state to SHORT.
  246. @type cmd: L{bytes}
  247. @param cmd: A POP3 command.
  248. @type args: L{bytes}
  249. @param args: The command arguments.
  250. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  251. L{bytes} or fails with L{ServerErrorResponse}
  252. @return: A deferred which fires when the entire response is received.
  253. On an OK response, it returns the response from the server minus
  254. the status indicator. On an ERR response, it issues a server
  255. error response failure with the response from the server minus the
  256. status indicator.
  257. """
  258. d = self._blocked(self.sendShort, cmd, args)
  259. if d is not None:
  260. return d
  261. if args:
  262. self.sendLine(cmd + b" " + args)
  263. else:
  264. self.sendLine(cmd)
  265. self.state = "SHORT"
  266. self._waiting = defer.Deferred()
  267. return self._waiting
  268. def sendLong(self, cmd, args, consumer, xform):
  269. """
  270. Send a POP3 command to which a multi-line response is expected.
  271. Block all further commands from being sent until the entire response is
  272. received. Transition the state to LONG_INITIAL.
  273. @type cmd: L{bytes}
  274. @param cmd: A POP3 command.
  275. @type args: L{bytes}
  276. @param args: The command arguments.
  277. @type consumer: callable that takes L{object}
  278. @param consumer: A consumer function which should be used to put
  279. the values derived by a transform function from each line of the
  280. multi-line response into a list.
  281. @type xform: L{None} or callable that takes
  282. L{bytes} and returns L{object}
  283. @param xform: A transform function which should be used to transform
  284. each line of the multi-line response into usable values for use by
  285. a consumer function. If L{None}, each line of the multi-line
  286. response should be sent directly to the consumer function.
  287. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  288. callable that takes L{object} and fails with L{ServerErrorResponse}
  289. @return: A deferred which fires when the entire response is received.
  290. On an OK response, it returns the consumer function. On an ERR
  291. response, it issues a server error response failure with the
  292. response from the server minus the status indicator and the
  293. consumer function.
  294. """
  295. d = self._blocked(self.sendLong, cmd, args, consumer, xform)
  296. if d is not None:
  297. return d
  298. if args:
  299. self.sendLine(cmd + b" " + args)
  300. else:
  301. self.sendLine(cmd)
  302. self.state = "LONG_INITIAL"
  303. self._xform = xform
  304. self._consumer = consumer
  305. self._waiting = defer.Deferred()
  306. return self._waiting
  307. # Twisted protocol callback
  308. def connectionMade(self):
  309. """
  310. Wait for a greeting from the server after the connection has been made.
  311. Start the connection in the WELCOME state.
  312. """
  313. if self.timeout > 0:
  314. self.setTimeout(self.timeout)
  315. self.state = "WELCOME"
  316. self._blockedQueue = []
  317. def timeoutConnection(self):
  318. """
  319. Drop the connection when the server does not respond in time.
  320. """
  321. self._timedOut = True
  322. self.transport.loseConnection()
  323. def connectionLost(self, reason):
  324. """
  325. Clean up when the connection has been lost.
  326. When the loss of connection was initiated by the client due to a
  327. timeout, the L{_timedOut} flag will be set. When it was initiated by
  328. the client due to an error in the server greeting, L{_greetingError}
  329. will be set to the server response minus the status indicator.
  330. @type reason: L{Failure <twisted.python.failure.Failure>}
  331. @param reason: The reason the connection was terminated.
  332. """
  333. if self.timeout > 0:
  334. self.setTimeout(None)
  335. if self._timedOut:
  336. reason = error.TimeoutError()
  337. elif self._greetingError:
  338. reason = ServerErrorResponse(self._greetingError)
  339. d = []
  340. if self._waiting is not None:
  341. d.append(self._waiting)
  342. self._waiting = None
  343. if self._blockedQueue is not None:
  344. d.extend([deferred for (deferred, f, a) in self._blockedQueue])
  345. self._blockedQueue = None
  346. for w in d:
  347. w.errback(reason)
  348. def lineReceived(self, line):
  349. """
  350. Pass a received line to a state machine function and
  351. transition to the next state.
  352. @type line: L{bytes}
  353. @param line: A received line.
  354. """
  355. if self.timeout > 0:
  356. self.resetTimeout()
  357. state = self.state
  358. self.state = None
  359. state = getattr(self, "state_" + state)(line) or state
  360. if self.state is None:
  361. self.state = state
  362. def lineLengthExceeded(self, buffer):
  363. """
  364. Drop the connection when a server response exceeds the maximum line
  365. length (L{LineOnlyReceiver.MAX_LENGTH}).
  366. @type buffer: L{bytes}
  367. @param buffer: A received line which exceeds the maximum line length.
  368. """
  369. # XXX - We need to be smarter about this
  370. if self._waiting is not None:
  371. waiting, self._waiting = self._waiting, None
  372. waiting.errback(LineTooLong())
  373. self.transport.loseConnection()
  374. # POP3 Client state logic - don't touch this.
  375. def state_WELCOME(self, line):
  376. """
  377. Handle server responses for the WELCOME state in which the server
  378. greeting is expected.
  379. WELCOME is the first state. The server should send one line of text
  380. with a greeting and possibly an APOP challenge. Transition the state
  381. to WAITING.
  382. @type line: L{bytes}
  383. @param line: A line received from the server.
  384. @rtype: L{bytes}
  385. @return: The next state.
  386. """
  387. code, status = _codeStatusSplit(line)
  388. if code != OK:
  389. self._greetingError = status
  390. self.transport.loseConnection()
  391. else:
  392. m = self._challengeMagicRe.search(status)
  393. if m is not None:
  394. self.serverChallenge = m.group(1)
  395. self.serverGreeting(status)
  396. self._unblock()
  397. return "WAITING"
  398. def state_WAITING(self, line):
  399. """
  400. Log an error for server responses received in the WAITING state during
  401. which the server is not expected to send anything.
  402. @type line: L{bytes}
  403. @param line: A line received from the server.
  404. """
  405. log.msg("Illegal line from server: " + repr(line))
  406. def state_SHORT(self, line):
  407. """
  408. Handle server responses for the SHORT state in which the server is
  409. expected to send a single line response.
  410. Parse the response and fire the deferred which is waiting on receipt of
  411. a complete response. Transition the state back to WAITING.
  412. @type line: L{bytes}
  413. @param line: A line received from the server.
  414. @rtype: L{bytes}
  415. @return: The next state.
  416. """
  417. deferred, self._waiting = self._waiting, None
  418. self._unblock()
  419. code, status = _codeStatusSplit(line)
  420. if code == OK:
  421. deferred.callback(status)
  422. else:
  423. deferred.errback(ServerErrorResponse(status))
  424. return "WAITING"
  425. def state_LONG_INITIAL(self, line):
  426. """
  427. Handle server responses for the LONG_INITIAL state in which the server
  428. is expected to send the first line of a multi-line response.
  429. Parse the response. On an OK response, transition the state to
  430. LONG. On an ERR response, cleanup and transition the state to
  431. WAITING.
  432. @type line: L{bytes}
  433. @param line: A line received from the server.
  434. @rtype: L{bytes}
  435. @return: The next state.
  436. """
  437. code, status = _codeStatusSplit(line)
  438. if code == OK:
  439. return "LONG"
  440. consumer = self._consumer
  441. deferred = self._waiting
  442. self._consumer = self._waiting = self._xform = None
  443. self._unblock()
  444. deferred.errback(ServerErrorResponse(status, consumer))
  445. return "WAITING"
  446. def state_LONG(self, line):
  447. """
  448. Handle server responses for the LONG state in which the server is
  449. expected to send a non-initial line of a multi-line response.
  450. On receipt of the last line of the response, clean up, fire the
  451. deferred which is waiting on receipt of a complete response, and
  452. transition the state to WAITING. Otherwise, pass the line to the
  453. transform function, if provided, and then the consumer function.
  454. @type line: L{bytes}
  455. @param line: A line received from the server.
  456. @rtype: L{bytes}
  457. @return: The next state.
  458. """
  459. # This is the state for each line of a long response.
  460. if line == b".":
  461. consumer = self._consumer
  462. deferred = self._waiting
  463. self._consumer = self._waiting = self._xform = None
  464. self._unblock()
  465. deferred.callback(consumer)
  466. return "WAITING"
  467. else:
  468. if self._xform is not None:
  469. self._consumer(self._xform(line))
  470. else:
  471. self._consumer(line)
  472. return "LONG"
  473. # Callbacks - override these
  474. def serverGreeting(self, greeting):
  475. """
  476. Handle the server greeting.
  477. @type greeting: L{bytes}
  478. @param greeting: The server greeting minus the status indicator.
  479. For servers implementing APOP authentication, this will contain a
  480. challenge string.
  481. """
  482. # External API - call these (most of 'em anyway)
  483. def startTLS(self, contextFactory=None):
  484. """
  485. Switch to encrypted communication using TLS.
  486. The first step of switching to encrypted communication is obtaining
  487. the server's capabilities. When that is complete, the L{_startTLS}
  488. callback function continues the switching process.
  489. @type contextFactory: L{None} or
  490. L{ClientContextFactory <twisted.internet.ssl.ClientContextFactory>}
  491. @param contextFactory: The context factory with which to negotiate TLS.
  492. If not provided, try to create a new one.
  493. @rtype: L{Deferred <defer.Deferred>} which successfully results in
  494. L{dict} mapping L{bytes} to L{list} of L{bytes} and/or L{bytes} to
  495. L{None} or fails with L{TLSError}
  496. @return: A deferred which fires when the transport has been
  497. secured according to the given context factory with the server
  498. capabilities, or which fails with a TLS error if the transport
  499. cannot be secured.
  500. """
  501. tls = interfaces.ITLSTransport(self.transport, None)
  502. if tls is None:
  503. return defer.fail(
  504. TLSError(
  505. "POP3Client transport does not implement "
  506. "interfaces.ITLSTransport"
  507. )
  508. )
  509. if contextFactory is None:
  510. contextFactory = self._getContextFactory()
  511. if contextFactory is None:
  512. return defer.fail(
  513. TLSError(
  514. "POP3Client requires a TLS context to "
  515. "initiate the STLS handshake"
  516. )
  517. )
  518. d = self.capabilities()
  519. d.addCallback(self._startTLS, contextFactory, tls)
  520. return d
  521. def _startTLS(self, caps, contextFactory, tls):
  522. """
  523. Continue the process of switching to encrypted communication.
  524. This callback function runs after the server capabilities are received.
  525. The next step is sending the server an STLS command to request a
  526. switch to encrypted communication. When an OK response is received,
  527. the L{_startedTLS} callback function completes the switch to encrypted
  528. communication. Then, the new server capabilities are requested.
  529. @type caps: L{dict} mapping L{bytes} to L{list} of L{bytes} and/or
  530. L{bytes} to L{None}
  531. @param caps: The server capabilities.
  532. @type contextFactory: L{ClientContextFactory
  533. <twisted.internet.ssl.ClientContextFactory>}
  534. @param contextFactory: A context factory with which to negotiate TLS.
  535. @type tls: L{ITLSTransport <interfaces.ITLSTransport>}
  536. @param tls: A TCP transport that supports switching to TLS midstream.
  537. @rtype: L{Deferred <defer.Deferred>} which successfully triggers with
  538. L{dict} mapping L{bytes} to L{list} of L{bytes} and/or L{bytes} to
  539. L{None} or fails with L{TLSNotSupportedError}
  540. @return: A deferred which successfully fires when the response from
  541. the server to the request to start TLS has been received and the
  542. new server capabilities have been received or fails when the server
  543. does not support TLS.
  544. """
  545. assert (
  546. not self.startedTLS
  547. ), "Client and Server are currently communicating via TLS"
  548. if b"STLS" not in caps:
  549. return defer.fail(
  550. TLSNotSupportedError(
  551. "Server does not support secure communication " "via TLS / SSL"
  552. )
  553. )
  554. d = self.sendShort(b"STLS", None)
  555. d.addCallback(self._startedTLS, contextFactory, tls)
  556. d.addCallback(lambda _: self.capabilities())
  557. return d
  558. def _startedTLS(self, result, context, tls):
  559. """
  560. Complete the process of switching to encrypted communication.
  561. This callback function runs after the response to the STLS command has
  562. been received.
  563. The final steps are discarding the cached capabilities and initiating
  564. TLS negotiation on the transport.
  565. @type result: L{dict} mapping L{bytes} to L{list} of L{bytes} and/or
  566. L{bytes} to L{None}
  567. @param result: The server capabilities.
  568. @type context: L{ClientContextFactory
  569. <twisted.internet.ssl.ClientContextFactory>}
  570. @param context: A context factory with which to negotiate TLS.
  571. @type tls: L{ITLSTransport <interfaces.ITLSTransport>}
  572. @param tls: A TCP transport that supports switching to TLS midstream.
  573. @rtype: L{dict} mapping L{bytes} to L{list} of L{bytes} and/or L{bytes}
  574. to L{None}
  575. @return: The server capabilities.
  576. """
  577. self.transport = tls
  578. self.transport.startTLS(context)
  579. self._capCache = None
  580. self.startedTLS = True
  581. return result
  582. def _getContextFactory(self):
  583. """
  584. Get a context factory with which to negotiate TLS.
  585. @rtype: L{None} or
  586. L{ClientContextFactory <twisted.internet.ssl.ClientContextFactory>}
  587. @return: A context factory or L{None} if TLS is not supported on the
  588. client.
  589. """
  590. try:
  591. from twisted.internet import ssl
  592. except ImportError:
  593. return None
  594. else:
  595. context = ssl.ClientContextFactory()
  596. context.method = ssl.SSL.TLSv1_2_METHOD
  597. return context
  598. def login(self, username, password):
  599. """
  600. Log in to the server.
  601. If APOP is available it will be used. Otherwise, if TLS is
  602. available, an encrypted session will be started and plaintext
  603. login will proceed. Otherwise, if L{allowInsecureLogin} is set,
  604. insecure plaintext login will proceed. Otherwise,
  605. L{InsecureAuthenticationDisallowed} will be raised.
  606. The first step of logging into the server is obtaining the server's
  607. capabilities. When that is complete, the L{_login} callback function
  608. continues the login process.
  609. @type username: L{bytes}
  610. @param username: The username with which to log in.
  611. @type password: L{bytes}
  612. @param password: The password with which to log in.
  613. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  614. L{bytes}
  615. @return: A deferred which fires when the login process is complete.
  616. On a successful login, it returns the server's response minus the
  617. status indicator.
  618. """
  619. d = self.capabilities()
  620. d.addCallback(self._login, username, password)
  621. return d
  622. def _login(self, caps, username, password):
  623. """
  624. Continue the process of logging in to the server.
  625. This callback function runs after the server capabilities are received.
  626. If the server provided a challenge in the greeting, proceed with an
  627. APOP login. Otherwise, if the server and the transport support
  628. encrypted communication, try to switch to TLS and then complete
  629. the login process with the L{_loginTLS} callback function. Otherwise,
  630. if insecure authentication is allowed, do a plaintext login.
  631. Otherwise, fail with an L{InsecureAuthenticationDisallowed} error.
  632. @type caps: L{dict} mapping L{bytes} to L{list} of L{bytes} and/or
  633. L{bytes} to L{None}
  634. @param caps: The server capabilities.
  635. @type username: L{bytes}
  636. @param username: The username with which to log in.
  637. @type password: L{bytes}
  638. @param password: The password with which to log in.
  639. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  640. L{bytes}
  641. @return: A deferred which fires when the login process is complete.
  642. On a successful login, it returns the server's response minus the
  643. status indicator.
  644. """
  645. if self.serverChallenge is not None:
  646. return self._apop(username, password, self.serverChallenge)
  647. tryTLS = b"STLS" in caps
  648. # If our transport supports switching to TLS, we might want to
  649. # try to switch to TLS.
  650. tlsableTransport = interfaces.ITLSTransport(self.transport, None) is not None
  651. # If our transport is not already using TLS, we might want to
  652. # try to switch to TLS.
  653. nontlsTransport = interfaces.ISSLTransport(self.transport, None) is None
  654. if not self.startedTLS and tryTLS and tlsableTransport and nontlsTransport:
  655. d = self.startTLS()
  656. d.addCallback(self._loginTLS, username, password)
  657. return d
  658. elif self.startedTLS or not nontlsTransport or self.allowInsecureLogin:
  659. return self._plaintext(username, password)
  660. else:
  661. return defer.fail(InsecureAuthenticationDisallowed())
  662. def _loginTLS(self, res, username, password):
  663. """
  664. Do a plaintext login over an encrypted transport.
  665. This callback function runs after the transport switches to encrypted
  666. communication.
  667. @type res: L{dict} mapping L{bytes} to L{list} of L{bytes} and/or
  668. L{bytes} to L{None}
  669. @param res: The server capabilities.
  670. @type username: L{bytes}
  671. @param username: The username with which to log in.
  672. @type password: L{bytes}
  673. @param password: The password with which to log in.
  674. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  675. L{bytes} or fails with L{ServerErrorResponse}
  676. @return: A deferred which fires when the server accepts the username
  677. and password or fails when the server rejects either. On a
  678. successful login, it returns the server's response minus the
  679. status indicator.
  680. """
  681. return self._plaintext(username, password)
  682. def _plaintext(self, username, password):
  683. """
  684. Perform a plaintext login.
  685. @type username: L{bytes}
  686. @param username: The username with which to log in.
  687. @type password: L{bytes}
  688. @param password: The password with which to log in.
  689. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  690. L{bytes} or fails with L{ServerErrorResponse}
  691. @return: A deferred which fires when the server accepts the username
  692. and password or fails when the server rejects either. On a
  693. successful login, it returns the server's response minus the
  694. status indicator.
  695. """
  696. return self.user(username).addCallback(lambda r: self.password(password))
  697. def _apop(self, username, password, challenge):
  698. """
  699. Perform an APOP login.
  700. @type username: L{bytes}
  701. @param username: The username with which to log in.
  702. @type password: L{bytes}
  703. @param password: The password with which to log in.
  704. @type challenge: L{bytes}
  705. @param challenge: A challenge string.
  706. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  707. L{bytes} or fails with L{ServerErrorResponse}
  708. @return: A deferred which fires when the server response is received.
  709. On a successful login, it returns the server response minus
  710. the status indicator.
  711. """
  712. digest = md5(challenge + password).hexdigest().encode("ascii")
  713. return self.apop(username, digest)
  714. def apop(self, username, digest):
  715. """
  716. Send an APOP command to perform authenticated login.
  717. This should be used in special circumstances only, when it is
  718. known that the server supports APOP authentication, and APOP
  719. authentication is absolutely required. For the common case,
  720. use L{login} instead.
  721. @type username: L{bytes}
  722. @param username: The username with which to log in.
  723. @type digest: L{bytes}
  724. @param digest: The challenge response to authenticate with.
  725. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  726. L{bytes} or fails with L{ServerErrorResponse}
  727. @return: A deferred which fires when the server response is received.
  728. On an OK response, the deferred succeeds with the server
  729. response minus the status indicator. On an ERR response, the
  730. deferred fails with a server error response failure.
  731. """
  732. return self.sendShort(b"APOP", username + b" " + digest)
  733. def user(self, username):
  734. """
  735. Send a USER command to perform the first half of plaintext login.
  736. Unless this is absolutely required, use the L{login} method instead.
  737. @type username: L{bytes}
  738. @param username: The username with which to log in.
  739. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  740. L{bytes} or fails with L{ServerErrorResponse}
  741. @return: A deferred which fires when the server response is received.
  742. On an OK response, the deferred succeeds with the server
  743. response minus the status indicator. On an ERR response, the
  744. deferred fails with a server error response failure.
  745. """
  746. return self.sendShort(b"USER", username)
  747. def password(self, password):
  748. """
  749. Send a PASS command to perform the second half of plaintext login.
  750. Unless this is absolutely required, use the L{login} method instead.
  751. @type password: L{bytes}
  752. @param password: The plaintext password with which to authenticate.
  753. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  754. L{bytes} or fails with L{ServerErrorResponse}
  755. @return: A deferred which fires when the server response is received.
  756. On an OK response, the deferred succeeds with the server
  757. response minus the status indicator. On an ERR response, the
  758. deferred fails with a server error response failure.
  759. """
  760. return self.sendShort(b"PASS", password)
  761. def delete(self, index):
  762. """
  763. Send a DELE command to delete a message from the server.
  764. @type index: L{int}
  765. @param index: The 0-based index of the message to delete.
  766. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  767. L{bytes} or fails with L{ServerErrorResponse}
  768. @return: A deferred which fires when the server response is received.
  769. On an OK response, the deferred succeeds with the server
  770. response minus the status indicator. On an ERR response, the
  771. deferred fails with a server error response failure.
  772. """
  773. return self.sendShort(b"DELE", b"%d" % (index + 1,))
  774. def _consumeOrSetItem(self, cmd, args, consumer, xform):
  775. """
  776. Send a command to which a long response is expected and process the
  777. multi-line response into a list accounting for deleted messages.
  778. @type cmd: L{bytes}
  779. @param cmd: A POP3 command to which a long response is expected.
  780. @type args: L{bytes}
  781. @param args: The command arguments.
  782. @type consumer: L{None} or callable that takes
  783. L{object}
  784. @param consumer: L{None} or a function that consumes the output from
  785. the transform function.
  786. @type xform: L{None}, callable that takes
  787. L{bytes} and returns 2-L{tuple} of (0) L{int}, (1) L{object},
  788. or callable that takes L{bytes} and returns L{object}
  789. @param xform: A function that parses a line from a multi-line response
  790. and transforms the values into usable form for input to the
  791. consumer function. If no consumer function is specified, the
  792. output must be a message index and corresponding value. If no
  793. transform function is specified, the line is used as is.
  794. @rtype: L{Deferred <defer.Deferred>} which fires with L{list} of
  795. L{object} or callable that takes L{list} of L{object}
  796. @return: A deferred which fires when the entire response has been
  797. received. When a consumer is not provided, the return value is a
  798. list of the value for each message or L{None} for deleted messages.
  799. Otherwise, it returns the consumer itself.
  800. """
  801. if consumer is None:
  802. L = []
  803. consumer = _ListSetter(L).setitem
  804. return self.sendLong(cmd, args, consumer, xform).addCallback(lambda r: L)
  805. return self.sendLong(cmd, args, consumer, xform)
  806. def _consumeOrAppend(self, cmd, args, consumer, xform):
  807. """
  808. Send a command to which a long response is expected and process the
  809. multi-line response into a list.
  810. @type cmd: L{bytes}
  811. @param cmd: A POP3 command which expects a long response.
  812. @type args: L{bytes}
  813. @param args: The command arguments.
  814. @type consumer: L{None} or callable that takes
  815. L{object}
  816. @param consumer: L{None} or a function that consumes the output from the
  817. transform function.
  818. @type xform: L{None} or callable that takes
  819. L{bytes} and returns L{object}
  820. @param xform: A function that transforms a line from a multi-line
  821. response into usable form for input to the consumer function. If
  822. no transform function is specified, the line is used as is.
  823. @rtype: L{Deferred <defer.Deferred>} which fires with L{list} of
  824. 2-L{tuple} of (0) L{int}, (1) L{object} or callable that
  825. takes 2-L{tuple} of (0) L{int}, (1) L{object}
  826. @return: A deferred which fires when the entire response has been
  827. received. When a consumer is not provided, the return value is a
  828. list of the transformed lines. Otherwise, it returns the consumer
  829. itself.
  830. """
  831. if consumer is None:
  832. L = []
  833. consumer = L.append
  834. return self.sendLong(cmd, args, consumer, xform).addCallback(lambda r: L)
  835. return self.sendLong(cmd, args, consumer, xform)
  836. def capabilities(self, useCache=True):
  837. """
  838. Send a CAPA command to retrieve the capabilities supported by
  839. the server.
  840. Not all servers support this command. If the server does not
  841. support this, it is treated as though it returned a successful
  842. response listing no capabilities. At some future time, this may be
  843. changed to instead seek out information about a server's
  844. capabilities in some other fashion (only if it proves useful to do
  845. so, and only if there are servers still in use which do not support
  846. CAPA but which do support POP3 extensions that are useful).
  847. @type useCache: L{bool}
  848. @param useCache: A flag that determines whether previously retrieved
  849. results should be used if available.
  850. @rtype: L{Deferred <defer.Deferred>} which successfully results in
  851. L{dict} mapping L{bytes} to L{list} of L{bytes} and/or L{bytes} to
  852. L{None}
  853. @return: A deferred which fires with a mapping of capability name to
  854. parameters. For example::
  855. C: CAPA
  856. S: +OK Capability list follows
  857. S: TOP
  858. S: USER
  859. S: SASL CRAM-MD5 KERBEROS_V4
  860. S: RESP-CODES
  861. S: LOGIN-DELAY 900
  862. S: PIPELINING
  863. S: EXPIRE 60
  864. S: UIDL
  865. S: IMPLEMENTATION Shlemazle-Plotz-v302
  866. S: .
  867. will be lead to a result of::
  868. | {'TOP': None,
  869. | 'USER': None,
  870. | 'SASL': ['CRAM-MD5', 'KERBEROS_V4'],
  871. | 'RESP-CODES': None,
  872. | 'LOGIN-DELAY': ['900'],
  873. | 'PIPELINING': None,
  874. | 'EXPIRE': ['60'],
  875. | 'UIDL': None,
  876. | 'IMPLEMENTATION': ['Shlemazle-Plotz-v302']}
  877. """
  878. if useCache and self._capCache is not None:
  879. return defer.succeed(self._capCache)
  880. cache = {}
  881. def consume(line):
  882. tmp = line.split()
  883. if len(tmp) == 1:
  884. cache[tmp[0]] = None
  885. elif len(tmp) > 1:
  886. cache[tmp[0]] = tmp[1:]
  887. def capaNotSupported(err):
  888. err.trap(ServerErrorResponse)
  889. return None
  890. def gotCapabilities(result):
  891. self._capCache = cache
  892. return cache
  893. d = self._consumeOrAppend(b"CAPA", None, consume, None)
  894. d.addErrback(capaNotSupported).addCallback(gotCapabilities)
  895. return d
  896. def noop(self):
  897. """
  898. Send a NOOP command asking the server to do nothing but respond.
  899. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  900. L{bytes} or fails with L{ServerErrorResponse}
  901. @return: A deferred which fires when the server response is received.
  902. On an OK response, the deferred succeeds with the server
  903. response minus the status indicator. On an ERR response, the
  904. deferred fails with a server error response failure.
  905. """
  906. return self.sendShort(b"NOOP", None)
  907. def reset(self):
  908. """
  909. Send a RSET command to unmark any messages that have been flagged
  910. for deletion on the server.
  911. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  912. L{bytes} or fails with L{ServerErrorResponse}
  913. @return: A deferred which fires when the server response is received.
  914. On an OK response, the deferred succeeds with the server
  915. response minus the status indicator. On an ERR response, the
  916. deferred fails with a server error response failure.
  917. """
  918. return self.sendShort(b"RSET", None)
  919. def retrieve(self, index, consumer=None, lines=None):
  920. """
  921. Send a RETR or TOP command to retrieve all or part of a message from
  922. the server.
  923. @type index: L{int}
  924. @param index: A 0-based message index.
  925. @type consumer: L{None} or callable that takes
  926. L{bytes}
  927. @param consumer: A function which consumes each transformed line from a
  928. multi-line response as it is received.
  929. @type lines: L{None} or L{int}
  930. @param lines: If specified, the number of lines of the message to be
  931. retrieved. Otherwise, the entire message is retrieved.
  932. @rtype: L{Deferred <defer.Deferred>} which fires with L{list} of
  933. L{bytes}, or callable that takes 2-L{tuple} of (0) L{int},
  934. (1) L{object}
  935. @return: A deferred which fires when the entire response has been
  936. received. When a consumer is not provided, the return value is a
  937. list of the transformed lines. Otherwise, it returns the consumer
  938. itself.
  939. """
  940. idx = b"%d" % (index + 1,)
  941. if lines is None:
  942. return self._consumeOrAppend(b"RETR", idx, consumer, _dotUnquoter)
  943. return self._consumeOrAppend(
  944. b"TOP", b"%b %d" % (idx, lines), consumer, _dotUnquoter
  945. )
  946. def stat(self):
  947. """
  948. Send a STAT command to get information about the size of the mailbox.
  949. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  950. a 2-tuple of (0) L{int}, (1) L{int} or fails with
  951. L{ServerErrorResponse}
  952. @return: A deferred which fires when the server response is received.
  953. On an OK response, the deferred succeeds with the number of
  954. messages in the mailbox and the size of the mailbox in octets.
  955. On an ERR response, the deferred fails with a server error
  956. response failure.
  957. """
  958. return self.sendShort(b"STAT", None).addCallback(_statXform)
  959. def listSize(self, consumer=None):
  960. """
  961. Send a LIST command to retrieve the sizes of all messages on the
  962. server.
  963. @type consumer: L{None} or callable that takes
  964. 2-L{tuple} of (0) L{int}, (1) L{int}
  965. @param consumer: A function which consumes the 0-based message index
  966. and message size derived from the server response.
  967. @rtype: L{Deferred <defer.Deferred>} which fires L{list} of L{int} or
  968. callable that takes 2-L{tuple} of (0) L{int}, (1) L{int}
  969. @return: A deferred which fires when the entire response has been
  970. received. When a consumer is not provided, the return value is a
  971. list of message sizes. Otherwise, it returns the consumer itself.
  972. """
  973. return self._consumeOrSetItem(b"LIST", None, consumer, _listXform)
  974. def listUID(self, consumer=None):
  975. """
  976. Send a UIDL command to retrieve the UIDs of all messages on the server.
  977. @type consumer: L{None} or callable that takes
  978. 2-L{tuple} of (0) L{int}, (1) L{bytes}
  979. @param consumer: A function which consumes the 0-based message index
  980. and UID derived from the server response.
  981. @rtype: L{Deferred <defer.Deferred>} which fires with L{list} of
  982. L{object} or callable that takes 2-L{tuple} of (0) L{int},
  983. (1) L{bytes}
  984. @return: A deferred which fires when the entire response has been
  985. received. When a consumer is not provided, the return value is a
  986. list of message sizes. Otherwise, it returns the consumer itself.
  987. """
  988. return self._consumeOrSetItem(b"UIDL", None, consumer, _uidXform)
  989. def quit(self):
  990. """
  991. Send a QUIT command to disconnect from the server.
  992. @rtype: L{Deferred <defer.Deferred>} which successfully fires with
  993. L{bytes} or fails with L{ServerErrorResponse}
  994. @return: A deferred which fires when the server response is received.
  995. On an OK response, the deferred succeeds with the server
  996. response minus the status indicator. On an ERR response, the
  997. deferred fails with a server error response failure.
  998. """
  999. return self.sendShort(b"QUIT", None)
  1000. __all__: List[str] = []