Hintsdb: USE_SQLITE build option
[exim.git] / doc / doc-txt / id-wellknown.txt
1 Internet Draft
2
3 Stream: Independent Submission
4 Category:
5 Date:           2024/05/26
6 Author:         J.Harris
7 Author:         B.Quatermass
8
9 --
10
11     Mailmaint Working Group                                      J. Harris
12     Internet Draft                                               Independent
13     Category: Experimental                                       B. Quatermass
14                                                                  Independent
15                                                                   May 2024
16
17 The WELLKNOWN SMTP Service Extension
18
19 Abstract
20 --------
21
22 This document defines a WELLKNOWN extension for the Simple Mail Transfer Protocol
23 (SMTP).  The extension provides the means for an SMTP server to inform a client
24 of information relating to the server which is intended to be public.
25
26 Status of this Memo
27 -------------------
28
29 This document is published for examination, experimental implementation, and
30 evaluation.
31
32 This document defines an Experimental Protocol for the Internet community.
33
34 This is a contribution to the RFC Series, independently of any other RFC
35 stream. The RFC Editor has chosen to publish this document at its discretion
36 and makes no statement about its value for implementation or deployment.
37
38 1. Introduction
39 ---------------
40
41 The Simple Mail Transfer Protocol [SMTP] provides the ability to transfer email
42 messages from a sending system to a recieving one.
43
44 Senders may on occasion wish to discover additional information, not directly
45 related to a specific email message, about the receiving system.  An example
46 is a contact point for discussing problems in communications.
47
48 The WELLKNOWN extension provides a means for delivering such information, by an
49 SMTP server on request from an SMTP client.
50
51 2. The WELLKNOWN SMTP Extension
52 ------------------------------
53
54 The extension mechanism for SMTP is defined in Section 2.2 of the current SMTP
55 specification [RFC5321a].
56
57 The name of the extension is WELLKNOWN.  Servers implementing this extension
58 advertise a WELLKNOWN as a keyword in the response to EHLO.  The keyword has no
59 parameters.
60
61 A new SMTP verb, "WELLKNOWN" is defined.
62
63 3. The WELLNOWN verb
64 --------------------
65
66 The format for the WELLKNOWN verb is:
67
68         WELLKNOWN <request-key>
69
70 The <request-key> parameter identifies the specific type of information being
71 requested.  It is separated from the verb by whitespace, and is xtext-encoded
72 per RFC 3461 Section 4 [RFC3461].
73
74 After the client gives the WELLKNOWN command, the server responds with one of
75 the 2xx, 4xx or 5xx response codes.
76
77 A success response MUST be a 250 response code, and MUST be multi-line.
78
79 The first line of a success response will be a response summary; the following
80 lines are the information data requested, xtext-encoded [RFC3461].  The encoded
81 information data MAY be split over multiple response lines.
82
83 A response summary MAY be empty.  In this case the first line of the response
84 will be only "250-".
85
86 A response summary MAY contain a size parameter, giving the number of bytes
87 of data.  This parameter is expressed as "SIZE=" followed by a decimal number.
88 The size value does not include the xtext-encoding overheader, the "250-" or
89 "250 " response code prefixing each line, nor the CR,LF bytes between lines.
90
91 4. Example
92 ----------
93
94 S: 220 ESMTP spoken here
95
96 C: EHLO test
97
98 S: 250-Hi there, mate
99 S: 250-SIZE
100 S: 250-LIMITS
101 S: 250-8BITMIME
102 S: 250-PIPELINING
103 S: 250-WELLKNOWN
104 S: 250 HELP
105
106 C: WELLKNOWN security.txt
107
108 S: 250-SIZE=285
109 S: 250-Contact:+20mailto:security@example.com+0A
110 S: 250-+0A
111 S: 250-Canonical:+20https://www.example.com/.well-known/security.txt+0A
112 S: 250-Canonical:+20mailserver://mx1.example.com/WELLKNOWN/security.txt+0A
113 S: 250-Canonical:+20mailserver://mx2.example.com/WELLKNOWN/security.txt+0A
114 S: 250-+0A
115 S: 250-Preferred-Languages:+20en+0A
116 S: 250-+0A
117 S: 250-Expires:+202025-02-01T00:00:00.000Z+0A
118 S: 250 +0A
119
120 C: QUIT
121
122 S: 221
123
124
125 5. Use Cases
126 ------------
127
128 5.1 security.txt
129 ---
130 It is common for a website to provide public-access information via the HTTP
131 protocol.  One such item, a "security.txt" file, is descibed in RFC 9116.
132
133 The WELLKNOWN extension provides a method for publishing similar information
134 for an SMTP host, without the need to operate an HTTP server.
135
136 It is RECOMMENDED that the request-key for this usage be "security.txt".
137
138 5.2 ACME handshake
139 ---
140 ACME [RFC8555] provides for obtaining a certificate, needed for encrpted
141 communications using TLS.  It defines handshake methods using the DNS and using
142 HTTP, for verifying ownership of the domain being certified.
143
144 The WELLKNOWN extension provides a method for operating a similar handshake,
145 without the need to operate an HTTP server or manipulate the DNS.