1Sendmail::PMilter::ContUesxetr(3C)ontributed Perl DocumeSnetnadtmiaoinl::PMilter::Context(3)
2
6 Copyright (c) 2016-2022 G.W. Haywood. All rights reserved.
7 With thanks to all those who have trodden these paths before,
8 including Copyright (c) 2002-2004 Todd Vierling. All rights
9 reserved.
10 Redistribution and use in source and binary forms, with or without
12 modification, are permitted provided that the following conditions are
13 met:
14 1. Redistributions of source code must retain the above copyright
16 notices, this list of conditions and the following disclaimer.
17 2. Redistributions in binary form must reproduce the above copyright
19 notices, this list of conditions and the following disclaimer in the
20 documentation and/or other materials provided with the distribution.
21 3. Neither the name of the author nor the names of contributors may be
23 used to endorse or promote products derived from this software without
24 specific prior written permission. In the case of G.W. Haywood this
25 permission is hereby now granted.
26 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
28 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
29 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
32 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
33 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
37 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38
40 Sendmail::PMilter::Context - per-connection milter context
41
43 A Sendmail::PMilter::Context is the context object passed to milter
44 callback functions as the first argument, typically named "$ctx" for
45 convenience. This document details the publicly accessible operations
46 on this object.
47
49 $ctx->getpriv
50 Returns the private data object for this milter instance, set by
51 $ctx->setpriv() (see below). Returns undef if setpriv has never
52 been called by this milter instance.
53 $ctx->getsymval(NAME)
55 (The word 'macro' in Sendmail parlance refers to named variables
56 which are essentially text strings. They can be defined by the
57 MTA, and populated as messages are processed, or by milters, or by
58 the MTA's configuration files.)
59 The getsymval method retrieves the macro symbol named NAME from the
61 macros
62 available from the MTA for the current callback. NAME is either a
63 one- character macro name, or a multi-character name enclosed in
64 {curly braces}. If macro NAME is undefined when getsymval is
65 called, it returns undef.
66 Some common macros are given below. The milter protocol was first
68 implemented in the Sendmail MTA, so these macro names are those
69 used by Sendmail itself; other MTAs e.g. Postfix may provide
70 similar macros.
71 $ctx->getsymval('_')
73 The remote host name and address, in standard SMTP "name
74 [address]" form.
75 $ctx->getsymval('i')
77 The MTA's queue ID for the current message.
78 $ctx->getsymval('j')
80 The MTA's idea of local host name.
81 $ctx->getsymval('{if_addr}')
83 The local address of the network interface upon which the
84 connection was received.
85 $ctx->getsymval('{if_name}')
87 The local hostname of the network interface upon which the
88 connection was received.
89 $ctx->getsymval('{mail_addr}')
91 The MAIL FROM: sender's address, canonicalized and angle bracket
92 stripped. (This is typically not the same value as the second
93 argument to the "envfrom" callback.) Will be defined to the
94 empty string '' if the client issued a MAIL FROM:<> null return
95 path command.
96 $ctx->getsymval('{rcpt_addr}')
98 The RCPT TO: recipient's address, canonicalized and angle bracket
99 stripped. (This is typically not the same value as the second
100 argument to the "envrcpt" callback.)
101 Not all macros may be available at all times. Some macros are only
103 available after a specific phase is reached, and some macros may
104 only be available from certain MTA implementations. Check returned
105 values for 'undef'. This version of the Sendmail::PMilter package
106 collects macro values only for the following callbacks:
107 CONNECT HELO ENVFROM ENVRCPT DATA EOH EOM
109 $ctx->setpriv(DATA)
111 This is the place to store milter-private data that is sensitive to
112 the current SMTP client connection. Only one value can be stored,
113 so typically an arrayref or hashref is initialized in the "connect"
114 callback and set with $ctx->setpriv.
115 This value can be retrieved on subsequent callback runs with
117 $ctx->getpriv.
118 $ctx->setreply(RCODE, XCODE, MESSAGE)
120 Set an extended SMTP status reply (before returning SMFIS_REJECT or
121 SMFIS_TEMPFAIL). RCODE should be a short (4xx or 5xx) numeric
122 reply code, XCODE should be a long ('4.x.y' or '5.x.y') ESMTP reply
123 code. The first digit of RCODE must be the same as the first digit
124 of XCODE. There is no such restriction on the other digits. In
125 RCODE and XCODE, 'x' should be one decimal digit; in XCODE 'y'
126 should be either one or two decimal digits. MESSAGE is the full
127 text of the message to send. Refer to the appropriate RFCs for
128 actual codes and suggested messages. Examples:
129 $ctx->setreply(451, '4.7.0', 'Cannot authenticate you right now');
131 return SMFIS_TEMPFAIL;
132 $ctx->setreply(550, '5.7.26', 'Multiple authentication failures');
134 return SMFIS_REJECT;
135 Note that after setting a reply with this method, the SMTP result
137 code comes from RCODE, not from the symbolic constants SMFIS_REJECT
138 and SMFIS_TEMPFAIL. However for consistency, callbacks that set a
139 4xx response code should use SMFIS_TEMPFAIL, and those that set a
140 5xx code should return SMFIS_REJECT.
141 Returns 1 on success, undef on failure. In the case of failure,
143 which is typically only caused by bad parameters, a generic message
144 will be sent based on the SMFIS_* return code.
145 $ctx->setmlreply(RCODE, XCODE, MESSAGES)
147 Set an extended SMTP status reply (before returning SMFIS_REJECT or
148 SMFIS_TEMPFAIL). See setreply() above for more information about
149 the reply codes RCODE and XCODE. MESSAGES is an array which
150 contains a multi-line reply. This array must contain no less than
151 two string elements. Sendmail dictates that it must contain no
152 more than 32 elements, and that each string element must contain no
153 more than 980 characters (although any of the strings may be NULL),
154 and no string may contain a newline ("\n") or a carriage return
155 ("\r") character.
156 Example:
158 $ctx->setmlreply(451, '4.7.0', \('Cannot authenticate sender.',
160 'Please refer to our published policies at',
161 'http://www.example.com/policies')
162 );
163 return SMFIS_TEMPFAIL;
164 Note that after setting a reply with this method, the SMTP result
166 code comes from RCODE, not from the symbolic constants SMFIS_REJECT
167 and SMFIS_TEMPFAIL. However for consistency, callbacks that set a
168 4xx response code should use SMFIS_TEMPFAIL, and those that set a
169 5xx code should return SMFIS_REJECT.
170 Returns 1 on success, undef on failure. In the case of failure,
172 which is typically caused by bad parameters, a generic message will
173 be sent based on the SMFIS_* return code.
174 $ctx->shutdown()
176 A special case of "$ctx->setreply()" which sets the short numeric
177 reply code to 421 and the ESMTP code to 4.7.0. Under Sendmail 8.13
178 and higher (and you should not be using any version of Sendmail
179 older than that), this will close the MTA's communication channel
180 quickly, which should immediately result in a "close" callback and
181 end of milter execution.
182 Returns 1.
184 $ctx->addheader(HEADER, VALUE)
186 Add header HEADER with value VALUE to this mail. Does not change
187 any existing headers with the same name. Only callable from the
188 "eom" callback.
189 Returns 1 on success, undef on failure.
191 $ctx->insheader(HEADER, VALUE, POSITION)
193 Insert header HEADER at position POSITION with value VALUE to this
194 mail. Does not change any existing headers with the same name.
195 Only callable from the "eom" callback. HEADER and VALUE are
196 requred, but POSITION is optional. A POSITION value of zero is
197 acceptable and is the default if not supplied - this inserts the
198 HEADER before all existing headers.
199 Returns 1 on success, undef on failure.
201 $ctx->chgheader(HEADER, INDEX, VALUE)
203 Change the INDEX'th header of name HEADER to the value VALUE. Only
204 callable from the "eom" callback. If INDEX exceeds the number of
205 existing headers of name HEADER, adds another header of that name.
206 Returns 1 on success, undef on failure.
208 $ctx->addrcpt(ADDRESS)
210 Add address ADDRESS to the list of recipients for this mail. Only
211 callable from the "eom" callback.
212 Returns 1 on success, undef on failure.
214 $ctx->addrcpt_par(ADDRESS,PARAMS)
216 Add an address ADDRESS and its ESMTP arguments PARAMS to the list
217 of recipients for this mail. Only callable from the "eom"
218 callback.
219 Returns 1 on success, undef on failure.
221 $ctx->delrcpt(ADDRESS)
223 Remove address ADDRESS from the list of recipients for this mail.
224 The ADDRESS argument must match a prior argument to the "envrcpt"
225 callback exactly (case sensitive, and including angle brackets if
226 present). Only callable from the "eom" callback.
227 Returns 1 on success, undef on failure. A success return means
229 that the command was queued for processing. It does not
230 necessarily mean that the recipient was successfully removed, that
231 information is not available from Sendmail.
232 $ctx->progress()
234 Sends an asynchronous "progress" message to the MTA, to allow
235 longer than normal operations such as extensive message body
236 scanning or a deliberate delay. This command should only be issued
237 during the EOM callback, it will fail (and return undef) if called
238 at other times.
239 Returns 1 if the call is made during EOM and is permitted, else
241 undef.
242 $ctx->quarantine(REASON)
244 Quarantine the current message in the MTA-defined quarantine area,
245 using the given REASON as a text string describing the quarantine
246 status. Only callable from the "eom" callback.
247 Returns 1 on success, undef on failure.
249 This method is an extension that is not available in the standard
251 Sendmail::Milter package.
252 $ctx->replacebody(BUFFER)
254 Replace the message body with the data in BUFFER (a scalar). This
255 method may be called multiple times, each call appending to the
256 replacement buffer. End-of-line should be represented by CR-LF
257 ("\r\n"). Only callable from the "eom" callback.
258 Returns 1 on success, undef on failure.
260 $ctx->chgfrom(ADDRESS) =item $ctx->setsender(ADDRESS) (Deprecated)
262 Replace the envelope sender address for the given mail message.
263 Returns 1 on success, undef on failure. Successful return means
265 that the command was queued for processing. It does not
266 necessarily mean that the operation was successfully completed,
267 that information is not available from Sendmail.
268
270 Sendmail::PMilter
271perl v5.36.0 2022-10-31 Sendmail::PMilter::Context(3)