From 13851bda5edd7d7a640373dadbcab61e530b750a Mon Sep 17 00:00:00 2001 From: nick evans Date: Mon, 7 Nov 2022 06:28:45 -0500 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=93=9A=20Add=20many=20more=20RFCs=20t?= =?UTF-8?q?o=20rake=20rfcs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- rakelib/rfcs.rake | 117 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 92 insertions(+), 25 deletions(-) diff --git a/rakelib/rfcs.rake b/rakelib/rfcs.rake index 772f2eb6..d232443c 100644 --- a/rakelib/rfcs.rake +++ b/rakelib/rfcs.rake @@ -2,38 +2,77 @@ RFCS = { + # Historic IMAP RFCs + 822 => "Internet Message Format (OBSOLETE)", + 1730 => "IMAP4 (OBSOLETE)", + 1731 => "IMAP4 Authentication Mechanisms (OBSOLETE)", + 2060 => "IMAP4rev1 (OBSOLETE)", + 2061 => "IMAP4 Compatibility with IMAP2bis", + 2062 => "Internet Message Access Protocol - Obsolete Syntax", + 2086 => "IMAP ACL (OBSOLETE)", + 2087 => "IMAP QUOTA (OBSOLETE)", + 2088 => "IMAP LITERAL+ (OBSOLETE)", + 2095 => "IMAP/POP AUTHorize Extension for CRAM-MD5 (OBSOLETE)", + 2192 => "IMAP URL Scheme (OBSOLETE)", + 2222 => "SASL (OBSOLETE)", + 2359 => "IMAP UIDPLUS (OBSOLETE)", + 2822 => "Internet Message Format (OBSOLETE)", + 3348 => "IMAP CHILDREN (OBSOLETED)", + 4551 => "IMAP CONDSTORE (OBSOLETE)", + 5162 => "IMAP QRESYNC (OBSOLETE)", + 6237 => "IMAP MULTISEARCH (OBSOLETE)", + + 2595 => "Using TLS with IMAP, POP3 and ACAP", + # Core IMAP RFCs - 2060 => "IMAP4rev1 (obsolete)", 3501 => "IMAP4rev1", # supported by nearly all email servers 4466 => "Collected Extensions to IMAP4 ABNF", - 9051 => "IMAP4rev2", + 9051 => "IMAP4rev2", # not widely supported yet # RFC-9051 Normative References (not a complete list) 2152 => "UTF-7", 2180 => "IMAP4 Multi-Accessed Mailbox Practice", 2683 => "IMAP4 Implementation Recommendations", - 5258 => "IMAP4 LIST-EXTENDED Extensions", + 3503 => "Message Disposition Notification (MDN) profile IMAP", + 5234 => "ABNF", 5788 => "IMAP4 keyword registry", 8314 => "Cleartext Considered Obsolete: Use of TLS for Email", + # Internet Message format and envelope and body structure + 5322 => "Internet Message Format (current)", + + 1864 => "[MD5]: The Content-MD5 Header Field", + 2045 => "[MIME-IMB]: MIME Part One: Format of Internet Message Bodies", + 2046 => "[MIME-IMT]: MIME Part Two: Media Types", + 2047 => "[MIME-HDRS]: MIME Part Three: Header Extensions for Non-ASCII Text", + 2183 => "[DISPOSITION]: The Content-Disposition Header", + 2231 => "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations", + 2557 => "[LOCATION]: MIME Encapsulation of Aggregate Documents", + 2978 => "[CHARSET]: IANA Charset Registration Procedures, BCP 19", + 3282 => "[LANGUAGE-TAGS]: Content Language Headers", + 6532 => "[I18N-HDRS]: Internationalized Email Headers", + # SASL - 4422 => "SASL, AUTH=EXTERNAL", - 4959 => "IMAP SASL-IR", + 4422 => "SASL, EXTERNAL", + # stringprep 3454 => "stringprep", 4013 => "SASLprep", 8265 => "PRECIS", # obsoletes SASLprep? + # SASL mechanisms (not a complete list) - 2195 => "AUTH=CRAM-MD5", - 4505 => "AUTH=ANONYMOUS", - 4616 => "AUTH=PLAIN", - 4752 => "AUTH=GSSAPI (Kerberos V5)", - 5802 => "AUTH=SCRAM-SHA-1", - 6331 => "AUTH=DIGEST-MD5", - 6595 => "AUTH=SAML20", - 6616 => "AUTH=OPENID20", - 7628 => "AUTH=OAUTH10A AUTH=OAUTHBEARER", - 7677 => "AUTH=SCRAM-SHA-256", + 2195 => "SASL CRAM-MD5", + 4505 => "SASL ANONYMOUS", + 4616 => "SASL PLAIN", + 4752 => "SASL GSSAPI (Kerberos V5)", + 5801 => "SASL GS2-*, GS2-KRB5", + 5802 => "SASL SCRAM-*, SCRAM-SHA-1, SCRAM-SHA1-PLUS", + 5803 => "LDAP Schema for Storing SCRAM Secrets", + 6331 => "SASL DIGEST-MD5", + 6595 => "SASL SAML20", + 6616 => "SASL OPENID20", + 7628 => "SASL OAUTH10A, OAUTHBEARER", + 7677 => "SASL SCRAM-SHA-256, SCRAM-SHA256-PLUS", # "Informational" RFCs 1733 => "Distributed E-Mail Models in IMAP4", @@ -49,36 +88,64 @@ RFCS = { # Other IMAP4 "Standards Track" RFCs 5092 => "IMAP URL Scheme", + 5593 => "IMAP URL Access Identifier Extension", 5530 => "IMAP Response Codes", 6186 => "Use of SRV Records for Locating Email Submission/Access Services", 8305 => "Happy Eyeballs Version 2: Better Connectivity Using Concurrency", # IMAP4 Extensions - 2087 => "IMAP QUOTA", 2177 => "IMAP IDLE", 2193 => "IMAP MAILBOX-REFERRALS", + 2221 => "IMAP LOGIN-REFERRALS", 2342 => "IMAP NAMESPACE", - 3348 => "IMAP CHILDREN", + 2971 => "IMAP ID", + 3502 => "IMAP MULTIAPPEND", 3516 => "IMAP BINARY", 3691 => "IMAP UNSELECT", 4314 => "IMAP ACL, RIGHTS=", 4315 => "IMAP UIDPLUS", - 4731 => "IMAP ESEARCH (for controlling what is returned)", - 5161 => "IMAP ENABLE Extension", - 5182 => "IMAP SEARCHRES (for referencing the last result)", - 5255 => "IMAP I18N: LANGUAGE, I18NLEVEL={1,2}", + 4467 => "IMAP URLAUTH", + 4469 => "IMAP CATENATE", + 4731 => "IMAP ESEARCH", + 4959 => "IMAP SASL-IR", + 4978 => "IMAP COMPRESS=DEFLATE", + 5032 => "IMAP WITHIN", + 5161 => "IMAP ENABLE", + 5182 => "IMAP SEARCHRES", + 5255 => "IMAP I18NLEVEL=1, I18NLEVEL=2, LANGUAGE", 5256 => "IMAP SORT, THREAD", + 5257 => "IMAP ANNOTATE-EXPERIMENT-1", + 5258 => "IMAP LIST-EXTENDED", + 5259 => "IMAP CONVERT", + 5267 => "IMAP CONTEXT=SEARCH, CONTEXT=SORT, ESORT", + 5464 => "IMAP METADATA, METADATA-SERVER", 5465 => "IMAP NOTIFY", + 5466 => "IMAP FILTERS", + 5524 => "IMAP URLAUTH=BINARY", # see also: [RFC Errata 6214] + 5550 => "IMAP URL-PARTIAL", + 5738 => "IMAP UTF8=ALL, UTF8=APPEND, UTF8=USER", # OBSOLETED by RFC6855 5819 => "IMAP LIST-STATUS", + 5957 => "IMAP SORT=DISPLAY", 6154 => "IMAP SPECIAL-USE, CREATE-SPECIAL-USE", + 6203 => "IMAP SEARCH=FUZZY", + 6785 => "IMAP IMAPSIEVE=", 6851 => "IMAP MOVE", - 6855 => "IMAP UTF8=", - 7162 => "IMAP CONDSTORE and QRESYNC (quick resynchronization)", - 7888 => "IMAP LITERAL+, LITERAL- (Non-synchronizing Literals)", - + 6855 => "IMAP UTF8=ACCEPT, UTF8=ONLY", + 7162 => "IMAP CONDSTORE, QRESYNC", + 7377 => "IMAP MULTISEARCH", + 7888 => "IMAP LITERAL+, LITERAL-", + 7889 => "IMAP APPENDLIMIT", 8437 => "IMAP UNAUTHENTICATE", 8438 => "IMAP STATUS=SIZE", + 8440 => "IMAP LIST-MYRIGHTS", 8474 => "IMAP OBJECTID", + 8508 => "IMAP REPLACE", + 8514 => "IMAP SAVEDATE", + 8970 => "IMAP PREVIEW", + 9208 => "IMAP QUOTA, QUOTA=, QUOTASET", + + # etc... + 6857 => "Post-Delivery Message Downgrading for I18n Email Messages", }.freeze From 981ea3091306eab10e84345bd8fabb2c282cd53f Mon Sep 17 00:00:00 2001 From: nick evans Date: Fri, 11 Nov 2022 16:13:59 -0500 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=93=9A=20Change=20References=20format?= =?UTF-8?q?=20(again)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switch to the official RFC citation format, as reported at each RFCs txt citation URL, e.g: https://www.rfc-editor.org/refs/ref9051.txt. Removed "EXT-" from any citations that were still using it, because that is how modern IMAP RFCs cite their references. Add links to relevant specifications for response data structs, without resorting to the full citation syntax. ---- This is closer to what the format had already been before I switched it up the last time (9cd562ac). I believe the earlier format was simply copy/pasted from the references section of whichever RFC was being used at the time (e.g. 2060 or 3501). But the RFC citation format has changed since then, too. I'd previously changed it to be more "readable". But since then I've added links throughout the documentation of methods and data types, only occasionally needing a list of "see also" links. That approach works and satisfies my readability concerns. So our references list should just be a standard list of citations and it would be better to use the official citation format. To consider: should we move the references list to a REFERENCES.md file? --- lib/net/imap.rb | 238 +++++++++++++++++++++++++--------- lib/net/imap/response_data.rb | 24 +++- 2 files changed, 192 insertions(+), 70 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 401edfec..56e3d833 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -152,72 +152,184 @@ module Net # # # == References + #-- + # TODO: Consider moving references list to REFERENCES.md or REFERENCES.rdoc. + #++ # - # [[IMAP[https://tools.ietf.org/html/rfc3501]]] - # Crispin, M. "INTERNET MESSAGE ACCESS PROTOCOL - \VERSION 4rev1", - # RFC-3501[https://tools.ietf.org/html/rfc3501], March 2003. (Note: - # obsoletes RFC-2060[https://tools.ietf.org/html/rfc2060], December 1996.) + # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]:: + # Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - \VERSION 4rev1", + # RFC 3501, DOI 10.17487/RFC3501, March 2003, + # . # - # [[LANGUAGE-TAGS[https://tools.ietf.org/html/rfc1766]]] - # Phillips, A. and Davis, M. "Tags for Identifying Languages", - # RFC-5646[https://tools.ietf.org/html/rfc5646], September 2009. - # (Note: obsoletes - # RFC-3066[https://tools.ietf.org/html/rfc3066], January 2001, - # RFC-4646[https://tools.ietf.org/html/rfc4646], September 2006, and - # RFC-1766[https://tools.ietf.org/html/rfc1766], March 1995.) + # [IMAP-ABNF-EXT[https://www.rfc-editor.org/rfc/rfc4466.html]]:: + # Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", + # RFC 4466, DOI 10.17487/RFC4466, April 2006, + # . # - # [[MD5[https://tools.ietf.org/html/rfc1864]]] - # Myers, J. and M. Rose, "The Content-MD5 Header Field", - # RFC-1864[https://tools.ietf.org/html/rfc1864], October 1995. + # Note: Net::IMAP cannot parse the entire RFC4466 grammar yet. + # + # [{IMAP4rev2}[https://www.rfc-editor.org/rfc/rfc9051.html]]:: + # Melnikov, A., Ed., and B. Leiba, Ed., "Internet Message Access Protocol + # (\IMAP) - Version 4rev2", RFC 9051, DOI 10.17487/RFC9051, August 2021, + # . + # + # Note: Net::IMAP is not fully compatible with IMAP4rev2 yet. + # + # [IMAP-IMPLEMENTATION[https://www.rfc-editor.org/info/rfc2683]]:: + # Leiba, B., "IMAP4 Implementation Recommendations", + # RFC 2683, DOI 10.17487/RFC2683, September 1999, + # . + # + # [IMAP-MULTIACCESS[https://www.rfc-editor.org/info/rfc2180]]:: + # Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC 2180, DOI + # 10.17487/RFC2180, July 1997, . + # + # [UTF7[https://tools.ietf.org/html/rfc2152]]:: + # Goldsmith, D. and M. Davis, "UTF-7 A Mail-Safe Transformation Format of + # Unicode", RFC 2152, DOI 10.17487/RFC2152, May 1997, + # . + # + # === Message envelope and body structure + # + # [RFC5322[https://tools.ietf.org/html/rfc5322]]:: + # Resnick, P., Ed., "Internet Message Format", + # RFC 5322, DOI 10.17487/RFC5322, October 2008, + # . # - # [[MIME-IMB[https://tools.ietf.org/html/rfc2045]]] - # Freed, N. and N. Borenstein, "MIME (Multipurpose Internet - # Mail Extensions) Part One: Format of Internet Message Bodies", - # RFC-2045[https://tools.ietf.org/html/rfc2045], November 1996. + # Note: obsoletes + # RFC-2822[https://tools.ietf.org/html/rfc2822] (April 2001) and + # RFC-822[https://tools.ietf.org/html/rfc822] (August 1982). # - # [[RFC-5322[https://tools.ietf.org/html/rfc5322]]] - # Resnick, P., "Internet Message Format", - # RFC-5322[https://tools.ietf.org/html/rfc5322], October 2008. - # (Note: obsoletes - # RFC-2822[https://tools.ietf.org/html/rfc2822], April 2001, and - # RFC-822[https://tools.ietf.org/html/rfc822], August 1982.) + # [CHARSET[https://tools.ietf.org/html/rfc2978]]:: + # Freed, N. and J. Postel, "IANA Charset Registration Procedures", BCP 19, + # RFC 2978, DOI 10.17487/RFC2978, October 2000, + # . # - # [[EXT-QUOTA[https://tools.ietf.org/html/rfc2087]]] - # Myers, J., "IMAP4 QUOTA extension", - # RFC-2087[https://tools.ietf.org/html/rfc2087], January 1997. + # [DISPOSITION[https://tools.ietf.org/html/rfc2183]]:: + # Troost, R., Dorner, S., and K. Moore, Ed., "Communicating Presentation + # Information in Internet Messages: The Content-Disposition Header + # Field", RFC 2183, DOI 10.17487/RFC2183, August 1997, + # . # - # [[EXT-NAMESPACE[https://tools.ietf.org/html/rfc2342]]] - # Gahrns, M. and Newman, C., "IMAP4 Namespace", - # RFC-2342[https://tools.ietf.org/html/rfc2342], May 1998. + # [MIME-IMB[https://tools.ietf.org/html/rfc2045]]:: + # Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions + # (MIME) Part One: Format of Internet Message Bodies", + # RFC 2045, DOI 10.17487/RFC2045, November 1996, + # . # - # [[EXT-ID[https://tools.ietf.org/html/rfc2971]]] - # Showalter, T., "IMAP4 ID extension", - # RFC-2971[https://tools.ietf.org/html/rfc2971], October 2000. + # [MIME-IMT[https://tools.ietf.org/html/rfc2046]]:: + # Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions + # (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, + # November 1996, . + # + # [MIME-HDRS[https://tools.ietf.org/html/rfc2047]]:: + # Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: + # Message Header Extensions for Non-ASCII Text", + # RFC 2047, DOI 10.17487/RFC2047, November 1996, + # . + # + # [RFC2231[https://tools.ietf.org/html/rfc2231]]:: + # Freed, N. and K. Moore, "MIME Parameter Value and Encoded Word + # Extensions: Character Sets, Languages, and Continuations", + # RFC 2231, DOI 10.17487/RFC2231, November 1997, + # . + # + # [I18n-HDRS[https://tools.ietf.org/html/rfc6532]]:: + # Yang, A., Steele, S., and N. Freed, "Internationalized Email Headers", + # RFC 6532, DOI 10.17487/RFC6532, February 2012, + # . + # + # [LANGUAGE-TAGS[https://www.rfc-editor.org/info/rfc3282]]:: + # Alvestrand, H., "Content Language Headers", + # RFC 3282, DOI 10.17487/RFC3282, May 2002, + # . + # + # [LOCATION[https://www.rfc-editor.org/info/rfc2557]]:: + # Palme, J., Hopmann, A., and N. Shelness, "MIME Encapsulation of + # Aggregate Documents, such as HTML (MHTML)", + # RFC 2557, DOI 10.17487/RFC2557, March 1999, + # . + # + # [MD5[https://tools.ietf.org/html/rfc1864]]:: + # Myers, J. and M. Rose, "The Content-MD5 Header Field", + # RFC 1864, DOI 10.17487/RFC1864, October 1995, + # . # - # [[EXT-ACL[https://tools.ietf.org/html/rfc4314]]] - # Melnikov, A., "IMAP4 ACL extension", - # RFC-4314[https://tools.ietf.org/html/rfc4314], December 2005. (Note: - # obsoletes RFC-2086[https://tools.ietf.org/html/rfc2086], January 1997.) + #-- + # TODO: Document IMAP keywords. # - # [[EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]] - # Crispin, M. and Muchison, K., "INTERNET MESSAGE ACCESS PROTOCOL - SORT - # and THREAD Extensions", RFC-5256[https://tools.ietf.org/html/rfc5256], - # June 2008. + # [RFC3503[https://tools.ietf.org/html/rfc3503]] + # Melnikov, A., "Message Disposition Notification (MDN) + # profile for Internet Message Access Protocol (IMAP)", + # RFC 3503, DOI 10.17487/RFC3503, March 2003, + # . + #++ # - # [[EXT-MOVE[https://tools.ietf.org/html/rfc6851]]] - # Gulbrandsen, A. and Freed, N., "Internet Message Access Protocol (\IMAP) - - # MOVE Extension", RFC-6851[https://tools.ietf.org/html/rfc6851], January - # 2013. + # === Supported \IMAP Extensions # - # [[OSSL]] - # http://www.openssl.org + # [QUOTA[https://tools.ietf.org/html/rfc2087]]:: + # Myers, J., "IMAP4 QUOTA extension", RFC 2087, DOI 10.17487/RFC2087, + # January 1997, . + #-- + # TODO: test compatibility with updated QUOTA extension: + # [QUOTA[https://tools.ietf.org/html/rfc9208]]:: + # Melnikov, A., "IMAP QUOTA Extension", RFC 9208, DOI 10.17487/RFC9208, + # March 2022, . + #++ + # [IDLE[https://tools.ietf.org/html/rfc2177]]:: + # Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177, + # June 1997, . + # [NAMESPACE[https://tools.ietf.org/html/rfc2342]]:: + # Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, + # DOI 10.17487/RFC2342, May 1998, . + # [ID[https://tools.ietf.org/html/rfc2971]]:: + # Showalter, T., "IMAP4 ID extension", RFC 2971, DOI 10.17487/RFC2971, + # October 2000, . + # [ACL[https://tools.ietf.org/html/rfc4314]]:: + # Melnikov, A., "IMAP4 Access Control List (ACL) Extension", RFC 4314, + # DOI 10.17487/RFC4314, December 2005, + # . + # [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]:: + # Crispin, M., "Internet Message Access Protocol (\IMAP) - UIDPLUS + # extension", RFC 4315, DOI 10.17487/RFC4315, December 2005, + # . + # [SORT[https://tools.ietf.org/html/rfc5256]]:: + # Crispin, M. and K. Murchison, "Internet Message Access Protocol - SORT and + # THREAD Extensions", RFC 5256, DOI 10.17487/RFC5256, June 2008, + # . + # [THREAD[https://tools.ietf.org/html/rfc5256]]:: + # Crispin, M. and K. Murchison, "Internet Message Access Protocol - SORT and + # THREAD Extensions", RFC 5256, DOI 10.17487/RFC5256, June 2008, + # . + # [RFC5530[https://www.rfc-editor.org/rfc/rfc5530.html]]:: + # Gulbrandsen, A., "IMAP Response Codes", RFC 5530, DOI 10.17487/RFC5530, + # May 2009, . + # [MOVE[https://tools.ietf.org/html/rfc6851]]:: + # Gulbrandsen, A. and N. Freed, Ed., "Internet Message Access Protocol + # (\IMAP) - MOVE Extension", RFC 6851, DOI 10.17487/RFC6851, January 2013, + # . # - # [[RSSL]] - # http://savannah.gnu.org/projects/rubypki + # === IANA registries # - # [[UTF7[https://tools.ietf.org/html/rfc2152]]] - # Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of - # Unicode", RFC-2152[https://tools.ietf.org/html/rfc2152], May 1997. + # * {IMAP Capabilities}[http://www.iana.org/assignments/imap4-capabilities] + # * {IMAP Response Codes}[https://www.iana.org/assignments/imap-response-codes/imap-response-codes.xhtml] + # * {IMAP Mailbox Name Attributes}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml] + # * {IMAP and JMAP Keywords}[https://www.iana.org/assignments/imap-jmap-keywords/imap-jmap-keywords.xhtml] + # * {IMAP Threading Algorithms}[https://www.iana.org/assignments/imap-threading-algorithms/imap-threading-algorithms.xhtml] + #-- + # * {IMAP Quota Resource Types}[http://www.iana.org/assignments/imap4-capabilities#imap-capabilities-2] + # * [{LIST-EXTENDED options and responses}[https://www.iana.org/assignments/imap-list-extended/imap-list-extended.xhtml] + # * {IMAP METADATA Server Entry and Mailbox Entry Registries}[https://www.iana.org/assignments/imap-metadata/imap-metadata.xhtml] + # * {IMAP ANNOTATE Extension Entries and Attributes}[https://www.iana.org/assignments/imap-annotate-extension/imap-annotate-extension.xhtml] + # * {IMAP URLAUTH Access Identifiers and Prefixes}[https://www.iana.org/assignments/urlauth-access-ids/urlauth-access-ids.xhtml] + # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml] + #++ + # * {SASL Mechanisms and SASL SCRAM Family Mechanisms}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml] + # * {Service Name and Transport Protocol Port Number Registry}[https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xml]: + # +imap+: tcp/143, +imaps+: tcp/993 + # * {GSSAPI/Kerberos/SASL Service Names}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml]: + # +imap+ + # * {Character sets}[https://www.iana.org/assignments/character-sets/character-sets.xhtml] # class IMAP < Protocol VERSION = "0.3.1" @@ -341,7 +453,7 @@ def capability # ) # end # - # See [EXT-ID[https://tools.ietf.org/html/rfc2971]] for field definitions. + # See [ID[https://tools.ietf.org/html/rfc2971]] for field definitions. def id(client_id=nil) synchronize do send_command("ID", ClientID.new(client_id)) @@ -597,7 +709,7 @@ def list(refname, mailbox) # end # end # - # The NAMESPACE extension is described in [EXT-NAMESPACE[https://tools.ietf.org/html/rfc2342]] + # The NAMESPACE extension is described in [NAMESPACE[https://tools.ietf.org/html/rfc2342]] def namespace synchronize do send_command("NAMESPACE") @@ -642,7 +754,7 @@ def xlist(refname, mailbox) # If this mailbox exists, it returns an array containing objects of type # Net::IMAP::MailboxQuotaRoot and Net::IMAP::MailboxQuota. # - # The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]] + # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]] def getquotaroot(mailbox) synchronize do send_command("GETQUOTAROOT", mailbox) @@ -658,7 +770,7 @@ def getquotaroot(mailbox) # Net::IMAP::MailboxQuota object is returned. This # command is generally only available to server admin. # - # The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]] + # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]] def getquota(mailbox) synchronize do send_command("GETQUOTA", mailbox) @@ -671,7 +783,7 @@ def getquota(mailbox) # mailbox. Typically one needs to be logged in as a server admin # for this to work. # - # The QUOTA extension is described in [EXT-QUOTA[https://tools.ietf.org/html/rfc2087]] + # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]] def setquota(mailbox, quota) if quota.nil? data = '()' @@ -685,7 +797,7 @@ def setquota(mailbox, quota) # +rights+ that user is to have on that mailbox. If +rights+ is nil, # then that user will be stripped of any rights to that mailbox. # - # The ACL extension is described in [EXT-ACL[https://tools.ietf.org/html/rfc4314]] + # The ACL extension is described in [ACL[https://tools.ietf.org/html/rfc4314]] def setacl(mailbox, user, rights) if rights.nil? send_command("SETACL", mailbox, user, "") @@ -698,7 +810,7 @@ def setacl(mailbox, user, rights) # If this mailbox exists, an array containing objects of # Net::IMAP::MailboxACLItem will be returned. # - # The ACL extension is described in [EXT-ACL[https://tools.ietf.org/html/rfc4314]] + # The ACL extension is described in [ACL[https://tools.ietf.org/html/rfc4314]] def getacl(mailbox) synchronize do send_command("GETACL", mailbox) @@ -1025,14 +1137,14 @@ def uid_move(set, mailbox) # p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII") # #=> [6, 7, 8, 1] # - # The SORT extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]. + # The SORT extension is described in [SORT[https://tools.ietf.org/html/rfc5256]]. def sort(sort_keys, search_keys, charset) return sort_internal("SORT", sort_keys, search_keys, charset) end # Similar to #sort, but returns an array of unique identifiers. # - # The SORT extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]. + # The SORT extension is described in [SORT[https://tools.ietf.org/html/rfc5256]]. def uid_sort(sort_keys, search_keys, charset) return sort_internal("UID SORT", sort_keys, search_keys, charset) end @@ -1071,7 +1183,7 @@ def remove_response_handler(handler) # Unlike #search, +charset+ is a required argument. US-ASCII # and UTF-8 are sample values. # - # The THREAD extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]. + # The THREAD extension is described in [THREAD[https://tools.ietf.org/html/rfc5256]]. def thread(algorithm, search_keys, charset) return thread_internal("THREAD", algorithm, search_keys, charset) end @@ -1079,7 +1191,7 @@ def thread(algorithm, search_keys, charset) # Similar to #thread, but returns unique identifiers instead of # message sequence numbers. # - # The THREAD extension is described in [EXT-SORT-THREAD[https://tools.ietf.org/html/rfc5256]]. + # The THREAD extension is described in [THREAD[https://tools.ietf.org/html/rfc5256]]. def uid_thread(algorithm, search_keys, charset) return thread_internal("UID THREAD", algorithm, search_keys, charset) end diff --git a/lib/net/imap/response_data.rb b/lib/net/imap/response_data.rb index 676a3bb5..bac4339a 100644 --- a/lib/net/imap/response_data.rb +++ b/lib/net/imap/response_data.rb @@ -116,6 +116,8 @@ class ResponseCode < Struct.new(:name, :data) # Net::IMAP::UIDPlusData represents the ResponseCode#data that accompanies # the +APPENDUID+ and +COPYUID+ response codes. # + # See [[UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]. + # # ==== Capability requirement # # The +UIDPLUS+ capability[rdoc-ref:Net::IMAP#capability] must be supported. @@ -130,13 +132,6 @@ class ResponseCode < Struct.new(:name, :data) # TODO: support MULTIAPPEND #++ # - # ==== References - # - # [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]:: - # Crispin, M., "Internet Message Access Protocol (IMAP) - UIDPLUS - # extension", RFC 4315, DOI 10.17487/RFC4315, December 2005, - # . - # class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids) ## # method: uidvalidity @@ -332,6 +327,11 @@ class StatusData < Struct.new(:mailbox, :attr) # [UID] # A number expressing the unique identifier of the message. # + # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2] + # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2] + # for full description of the standard fetch response data items, and + # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs. + # class FetchData < Struct.new(:seqno, :attr) end @@ -359,6 +359,11 @@ class FetchData < Struct.new(:seqno, :attr) # # message_id:: Returns a string that represents the message-id. # + # See [{IMAP4rev1 §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2]] + # and [{IMAP4rev2 §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2]] + # for full description of the envelope fields, and + # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs. + # class Envelope < Struct.new(:date, :subject, :from, :sender, :reply_to, :to, :cc, :bcc, :in_reply_to, :message_id) end @@ -440,6 +445,11 @@ class ThreadMember < Struct.new(:seqno, :children) # # multipart?:: Returns false. # + # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2] + # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2-4.9] + # for full description of all +BODYSTRUCTURE+ fields, and also + # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs. + # class BodyTypeBasic < Struct.new(:media_type, :subtype, :param, :content_id, :description, :encoding, :size, From cc6436c3c2ef5feb13a73afd1172b3ba3dfb73bf Mon Sep 17 00:00:00 2001 From: nick evans Date: Wed, 23 Nov 2022 08:25:00 -0500 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=93=9A=20More=20RFCs=E2=80=94related?= =?UTF-8?q?=20to=20TLS=20(&=20MD5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- rakelib/rfcs.rake | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/rakelib/rfcs.rake b/rakelib/rfcs.rake index d232443c..e22dee8c 100644 --- a/rakelib/rfcs.rake +++ b/rakelib/rfcs.rake @@ -22,8 +22,6 @@ RFCS = { 5162 => "IMAP QRESYNC (OBSOLETE)", 6237 => "IMAP MULTISEARCH (OBSOLETE)", - 2595 => "Using TLS with IMAP, POP3 and ACAP", - # Core IMAP RFCs 3501 => "IMAP4rev1", # supported by nearly all email servers 4466 => "Collected Extensions to IMAP4 ABNF", @@ -36,7 +34,6 @@ RFCS = { 3503 => "Message Disposition Notification (MDN) profile IMAP", 5234 => "ABNF", 5788 => "IMAP4 keyword registry", - 8314 => "Cleartext Considered Obsolete: Use of TLS for Email", # Internet Message format and envelope and body structure 5322 => "Internet Message Format (current)", @@ -77,10 +74,14 @@ RFCS = { # "Informational" RFCs 1733 => "Distributed E-Mail Models in IMAP4", 4549 => "Synchronization Operations for Disconnected IMAP4 Clients", - 6151 => "Updated Security Considerations for MD5 Message-Digest and HMAC-MD5", - # "Best Current Practice" RFCs + # TLS and other security concerns + 2595 => "Using TLS with IMAP, POP3 and ACAP", + 6151 => "Updated Security Considerations for MD5 Message-Digest and HMAC-MD5", 7525 => "Recommendations for Secure Use of TLS and DTLS", + 7818 => "Updated TLS Server Identity Check Procedure for Email Protocols", + 8314 => "Cleartext Considered Obsolete: Use of TLS for Email", + 8996 => "Deprecating TLS 1.0 and TLS 1.1,", # related email specifications 6376 => "DomainKeys Identified Mail (DKIM) Signatures", From 9539978a6a67fde523ef5160bce70c6027751b1b Mon Sep 17 00:00:00 2001 From: nick evans Date: Sun, 13 Nov 2022 16:29:35 -0500 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=94=A5=20Remove=20"openssl=20extensio?= =?UTF-8?q?ns=20must=20be=20installed"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "openssl" has been a default gem for a long time. Although some installations may still disable it, this is very rare and not important enough to document here any more. Looking at "net-http" and "net-smtp", neither of them still document the scenario where "openssl" is missing. Although it carefully avoids an implicit dependency, "net-http" doesn't try to catch any LoadError when an SSL connection is explicitly used. --- lib/net/imap.rb | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 56e3d833..300ddc9f 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -1269,9 +1269,7 @@ def idle_done # # port:: Port number (default value is 143 for imap, or 993 for imaps) # ssl:: If +options[:ssl]+ is true, then an attempt will be made - # to use SSL (now TLS) to connect to the server. For this to work - # OpenSSL [OSSL] and the Ruby OpenSSL [RSSL] extensions need to - # be installed. + # to use SSL (now TLS) to connect to the server. # If +options[:ssl]+ is a hash, it's passed to # OpenSSL::SSL::SSLContext#set_params as parameters. # open_timeout:: Seconds to wait until a connection is opened From 23c2a4f600c27af33d82f07718fff9ee76dbd74c Mon Sep 17 00:00:00 2001 From: nick evans Date: Mon, 14 Nov 2022 10:12:21 -0500 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20Add=20:nodoc:=20to?= =?UTF-8?q?=20RESPONSE=5FERRORS=20and=20client=5Fthread?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RESPONSE_ERRORS is used internally and should probably be private_const. client_thread should be removed (or deprecated). --- lib/net/imap.rb | 3 +-- lib/net/imap/errors.rb | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 300ddc9f..2a217e45 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -363,8 +363,7 @@ class IMAP < Protocol # Seconds to wait until an IDLE response is received. attr_reader :idle_response_timeout - # The thread to receive exceptions. - attr_accessor :client_thread + attr_accessor :client_thread # :nodoc: # Returns the debug mode. def self.debug diff --git a/lib/net/imap/errors.rb b/lib/net/imap/errors.rb index 33dd541c..b353756f 100644 --- a/lib/net/imap/errors.rb +++ b/lib/net/imap/errors.rb @@ -51,7 +51,7 @@ class ByeResponseError < ResponseError class UnknownResponseError < ResponseError end - RESPONSE_ERRORS = Hash.new(ResponseError) + RESPONSE_ERRORS = Hash.new(ResponseError) # :nodoc: RESPONSE_ERRORS["NO"] = NoResponseError RESPONSE_ERRORS["BAD"] = BadResponseError