1opendkim-lua(3) Library Functions Manual opendkim-lua(3)
2
6 opendkim-lua - Programming the OpenDKIM filter using Lua scripts
7
9 The OpenDKIM filter has hooks to run user-provided scripts for making
10 policy decisions regarding signatures to add on outbound messages or
11 verification and acceptance of messages inbound. The hooks take the
12 form of multiple Lua scripts which, if defined, are run at important
13 points during processing of a message.
14 For a full description of the Lua language, consult Lua programming
16 references (see below for a starting point). This man page only
17 describes the use of Lua in the context of OpenDKIM, specifically the
18 functions and global variables OpenDKIM provides for use in user-con‐
19 structed scripts beyond what Lua provides by default.
20 Unless otherwise noted, all functions described below return a single
22 result; on success they return the requested data, and on error they
23 return the Lua constant "nil".
24 Four scripting hooks are provided. They are as follows:
26 setup The setup script is run after all headers for the message have
28 been received but before any DKIM operations have started. At
29 this point the user can examine the available header fields to
30 decide whether the message should be signed or verified (or
31 both) and, if signing, which key(s) should be used to add signa‐
32 tures and which signature features are desired.
33 screen The screen script is run after the DKIM verification context has
35 been established. The main purpose of this script is to give
36 the user an opportunity to examine the message header fields
37 compared to the available DKIM signatures and determine which,
38 if any, should be ignored during verification. For example, the
39 user might decide only signatures added by domains exactly
40 matching that in the From: domain are acceptable, and the rest
41 should be ignored.
42 statistics
44 The statistics script is run after all of the DKIM verification
45 and signing work has been completed but before any final message
46 handling is done. The main purpose of this script is to give
47 the user an opportunity to examine the message or its signatures
48 and make arbitrary additional statistical observations that
49 should be recorded by the statistics module. (Experimental fea‐
50 ture not enabled for this installation.)
51 final The final script is run after all of the DKIM verification and
53 signing work has been completed. The user has an opportunity to
54 examine the results of all of the signature evaluations and make
55 a decision about whether or not the message should be accepted,
56 rejected, discarded, quarantined, etc. If the message is
57 accepted, any signatures requested earlier will be added to the
58 messages before it is released.
59
61 The following global variable(s) are provided for all user scripts:
62 ctx This is a generic context pointer referring to the context in
64 which the filtering operation is being performed. It represents
65 a single message in progress, and the connection that accepted
66 it.
67
69 These functions are made available to Lua for processing a message
70 through the setup script:
71 odkim.check_popauth(ctx)
73 Returns 1 if the SMTP client represented by ctx is coming from
74 an IP address found in the POPAUTH database (if enabled and con‐
75 figured), and 0 otherwise. Returns the Lua constant "nil" if
76 the POPAUTH database is not enabled or not configured.
77 odkim.db_check(db, string)
79 Returns 1 if db refers to a valid database handle (see
80 odkim.get_dbhandle() below) and string is found in that data‐
81 base, and 0 otherwise. If an error occurs, the Lua constant
82 "nil" is returned.
83 odkim.db_close(db)
85 Closes the specified data set. Returns 1. The current imple‐
86 mentation will conduct data set garbage collection when the
87 script terminates, so this is not strictly necessary, but is
88 recommended.
89 odkim.db_open(name[, icase])
91 Opens the data set specified by name. If icase is provided and
92 is "true", then queries into the database will be case-insensi‐
93 tive. See the opendkim(8) man page for information on specify‐
94 ing a data set. On success, returns a handle that can be passed
95 to odkim.db_check(); raises an exception on failure.
96 odkim.export(ctx, name, value[, name2, value2[, ...]])
98 Exports variables named with their corresponding values so that
99 they will be available to later scripts.
100 odkim.get_clienthost(ctx)
102 Returns the name of the host on the other end of the SMTP con‐
103 nection sending the current message. This is usually a host‐
104 name, but might be an IP address in square brackets if the SMTP
105 client's IP address does not have a name associated with it.
106 odkim.get_clientip(ctx)
108 Returns the IP address of the client on the other end of the
109 SMTP connection sending the current message as a string. Both
110 IPv4 and IPv6 addresses are supported.
111 odkim.get_dbhandle(ctx, db)
113 Returns a handle for the requested database that can be used in
114 later queries. The value of db should be one of DB_MTAS (data‐
115 base of MTA names whose mail should be signed), DB_MACROS (data‐
116 base of MTA macro checks to be done when determining signing),
117 DB_DOMAINS (database of domains to be signed), DB_SIGNINGTABLE
118 (database of signing table entries), DB_THIRDPARTY (database of
119 third party signatures to be trusted) and DB_DONTSIGNTO (data‐
120 base of recipients whose mail should not be signed). If the
121 requested database is not set in the current configuration file,
122 a Lua "nil" is returned.
123 odkim.get_envfrom(ctx)
125 Retrieves the SMTP envelope sender address for the message rep‐
126 resented by ctx.
127 odkim.get_fromdomain(ctx)
129 Retrieves the domain name of the sender of the message repre‐
130 sented by ctx.
131 odkim.get_header(ctx, name, n)
133 Retrieves the string contained in instance n of the header field
134 called name from the message represented by ctx, or the Lua con‐
135 stant "nil" if there was no such header field. Header field
136 numbering starts at 0, so use 0 for the first instance, 1 for
137 the second, etc. For example:
138 fromaddr = odkim.get_header(ctx, "From", 0)
140 This will return the value of the first (and hopefully only)
142 "From" header field. Negative values of n count backwards from
143 the end of the set of header fields, so:
144 rcvd = odkim.get_header(ctx, "Received", -2)
146 will retrieve the second-last Received: header field on the mes‐
148 sage.
149 odkim.get_mtasymbol(ctx, name)
151 Retrieves the value of the symbol called name from the MTA con‐
152 nection represented by ctx, or the Lua constant "nil" if the
153 requested symbol was not available at the time of the request.
154 odkim.get_rcpt(ctx, n)
156 Returns the nth envelope recipient for the message represented
157 by ctx. Recipient numbering starts at 0, so for the first
158 recipient, use 0 for n. If n references an out-of-range value,
159 the Lua constant "nil" is returned.
160 odkim.get_rcptarray(ctx)
162 Returns the envelope recipients for the message represented by
163 ctx in a single Lua array.
164 odkim.internal_ip(ctx)
166 Returns 1 if the SMTP client is coming from an internal IP
167 address, and 0 otherwise.
168 odkim.log(ctx, log)
170 Logs the string log if the current configuration requested log‐
171 ging. (Checking current configuration is why the ctx parameter
172 is required.)
173 odkim.rcpt_count(ctx)
175 Returns the count of envelope recipients on the message.
176 odkim.replace_header(ctx, name, n, newval)
178 Retrieves the value of in instance n of header field name in the
179 message referenced by ctx and replaces it with the string in
180 newval. See odkim.get_header() above for more information about
181 possible parameter values for n. Note that this only changes
182 the content of the header field used when generating or verify‐
183 ing the signature; the actual delivered message is not modified.
184 This can be used to anticipate how an intermediate mail transfer
185 agent might alter the message, thus correcting an avoidable sig‐
186 nature invalidation.
187 odkim.resign(ctx)
189 Arranges that the arriving message will be verified and then re-
190 signed in a single operation. Returns 1 on success or the Lua
191 constant "nil" on failure.
192 odkim.set_result(ctx, result)
194 Arranges to have the MTA return a specific result code in
195 response to the message represented by ctx. The value of result
196 must be one of SMFIS_TEMPFAIL (temporary failure/rejection),
197 SMFIS_ACCEPT (accept without further processing), SMFIS_DISCARD
198 (accept but discard the message) and SMFIS_REJECT (permanent
199 failure/rejection). Returns 1 on success or the Lua constant
200 "nil" on failure. Note that returning any of these codes indi‐
201 cates a final message disposition; the MTA will be told immedi‐
202 ately to take the specified action, and no further filter pro‐
203 cessing will occur.
204 odkim.sign(ctx[, keyname[, signer[, signlen]]])
206 Requests that the filter sign the message represented by ctx
207 using the specified keyname. The key name will be translated
208 into an actual domain, selector and private key via a query to
209 the KeyTable (see the opendkim.conf(5) page for details). The
210 keyname may be omitted if the KeyTable is not defined, meaning
211 the single signing domain, selector and key should be used to
212 sign. Returns 1 on success and 0 on failure. If a signer is
213 specified, the string there will be included in the generated
214 signature's "i=" tag. If a signlen is specified, the signature
215 will cover that many bytes of the message body. The order of
216 these last two parameters is interchangeable.
217 odkim.signfor(ctx, address[, multi])
219 Applies whatever signatures would be applied by default if the
220 candidate message had the specified address in the message's
221 From: field. The multi parameter, if "true" (default is
222 "false"), allows the application of multiple signatures.
223 Returns the number of signatures applied, which may be zero.
224 odkim.spam(ctx)
226 Tags the message as spam, for use in developing reputation about
227 domains that signed the message. Returns nothing. (Experimen‐
228 tal feature not enabled for this installation.)
229 odkim.use_ltag(ctx)
231 Requests that all signatures added to the message represented by
232 ctx include "l=" (body length) tags. Always returns the Lua
233 constant "nil".
234 odkim.verify(ctx)
236 Requests that the message represented by ctx be subjected to
237 DKIM signature verification. Returns the Lua constant "nil" on
238 success, or an error string on failure.
239 odkim.xtag(ctx, tag, value)
241 Requests that all signatures added to the message represented by
242 ctx include the named extension tag and value. Returns the num‐
243 ber of signatures successfully modified, or -1 on error. An
244 error can occur if the named tag is one already explicitly sup‐
245 ported by the DKIM library, or if there is a syntax error in the
246 tag or value.
247
249 The screen script has the following functions available to it, whose
250 descriptions can be found above: odkim.db_check, odkim.db_close,
251 odkim.db_open, odkim.export, odkim.get_dbhandle, odkim.get_envfrom,
252 odkim.get_fromdomain, odkim.get_header, odkim.get_mtasymbol,
253 odkim.get_rcpt, odkim.get_rcptarray, odkim.internal_ip, odkim.log,
254 odkim.rcpt_count, and odkim.spam.
255 The following additional functions are provided for this script:
257 odkim.get_sigarray(ctx)
259 Returns the complete set of signature handles found in the mes‐
260 sage represented by ctx, as a Lua array, or the Lua constant
261 "nil" in case of an error.
262 odkim.get_sigcount(ctx)
264 Returns the number of signatures found in the message repre‐
265 sented by ctx, or the Lua constant "nil" in case of an error.
266 odkim.get_sighandle(ctx, n)
268 Returns a handle representing an internal copy of the nth signa‐
269 ture found on the message represented by ctx. n must be a num‐
270 ber greater than or equal to zero (representing the first signa‐
271 ture) and less than the number of signatures on the message,
272 which can be determined using odkim.get_sigcount above. The
273 requested handle is returned on success, or the Lua constant
274 "nil" is returned on failure.
275 odkim.parse_field(string)
277 Parses the contents of a header field, provided as string, into
278 user and domain parts, discarding whitespace and comment compo‐
279 nents. Returns two strings, the user part and the domain part,
280 or the Lua constant "nil" in case of a parsing error.
281 odkim.sig_getdomain(sig)
283 Returns the name of the domain in the signature handle specified
284 by sig, previously returned by a call to odkim.get_sighandle().
285 This is taken from the signature's "d=" tag.
286 odkim.sig_getidentity(sig)
288 Returns the identity of the agent adding the signature handle
289 specified by sig, previously returned by a call to
290 odkim.get_sighandle(). This is taken from the signature's "i="
291 tag. This may be a default value and not one that was explic‐
292 itly part of the signature. If the identity could not be deter‐
293 mined, the Lua constant "nil" is returned.
294 odkim.sig_ignore(sig)
296 Instructs the verification code to ignore completely the signa‐
297 ture specified by sig, previously returned by a call to
298 odkim.get_sighandle(). Any pending verification of the message
299 will act as if that signature was not present on the message.
300 Always returns the Lua constant "nil".
301
303 The statistics script has the following functions available to it,
304 whose descriptions can be found above: odkim.export, odkim.get_envfrom,
305 odkim.get_header, odkim.get_mtasymbol, odkim.get_rcpt, odkim.get_rcp‐
306 tarray, odkim.get_sigarray, odkim.get_sigcount, odkim.get_sighandle,
307 odkim.internal_ip, odkim.log, odkim.parse_field, odkim.rcpt_count,
308 odkim.sig_getdomain, odkim.sig_getidentity, and odkim.spam.
309 The following functions are also available, defined in the next sec‐
311 tion: odkim.rbl_check, odkim.rcpt_count, odkim.sig_bhresult,
312 odkim.sig_bodylength, odkim.sig_canonlength, and odkim.sig_result.
313 The following additional function is provided for this script:
315 odkim.stats(ctx, name, value)
317 Records the additional statistic called name with its associated
318 value for the message represented by ctx.
319
321 The final script has the following functions available to it, whose
322 descriptions can be found above: odkim.get_clienthost, odkim.get_clien‐
323 tip, odkim.get_envfrom, odkim.get_fromdomain, odkim.get_header,
324 odkim.get_mtasymbol, odkim.get_rcpt, odkim.get_rcptarray,
325 odkim.get_sigarray, odkim.get_sigcount, odkim.get_sighandle,
326 odkim.internal_ip, odkim.log, odkim.parse_field, odkim.rcpt_count,
327 odkim.set_result, odkim.sig_getdomain, odkim.sig_getidentity,
328 odkim.spam, and odkim.xtags.
329 The following additional functions are provided for this script:
331 odkim.add_header(ctx, name, value)
333 Adds a new header field called name with the specified value to
334 the message represented by ctx. Returns 1 on success, or the
335 Lua constant "nil" on failure.
336 odkim.add_rcpt(ctx, addr)
338 Adds addr as an envelope recipient to the message represented by
339 ctx. Returns 1 on success, or the Lua constant "nil" on fail‐
340 ure.
341 odkim.del_header(ctx, name, n)
343 Deletes the nth instance (starting from 0) of the header field
344 called name from the message represented by ctx. Returns 1 on
345 success, or the Lua constant "nil" on failure.
346 odkim.del_rcpt(ctx, addr)
348 Deletes addr from the list of envelope recipients on the message
349 represented by ctx, and adds a new X-Original-Recipient: header
350 field containing the deleted address. Returns 1 on success, or
351 the Lua constant "nil" on failure.
352 odkim.quarantine(ctx, reason)
354 Asks the MTA to quarantine the message represented by ctx using
355 reason as a text string indicating the reason for the request.
356 Returns 1 on success or the Lua constant "nil" on failure.
357 odkim.rbl_check(ctx, query, qroot[, timeout])
359 Makes an RBL query. The root of the RBL is assumed to be at
360 qroot and the subject of the query is query, so the query per‐
361 formed will be query.qroot . The context handle ctx must also
362 be provided as it contains a handle to the established DNS ser‐
363 vice. The optional timeout parameter is the timeout to use, in
364 seconds. Returns "nil" on error, no values if the requested
365 record was not present in the RBL, or the four octets of the RBL
366 entry if it was. The octets are returned in big-endian order.
367 (Experimental feature not enabled for this installation.)
368 odkim.set_reply(ctx, rcode, xcode, message)
370 Instructs the MTA to return the specified SMTP reply to the
371 client sending the message represented by ctx. rcode must be a
372 three-digit SMTP reply code starting with 4 or 5 (for temporary
373 or permanent failures, respectively); xcode must be the empty
374 string or a valid extended reply code (see RFC2034) matching
375 rcode; and message must be the text portion of the SMTP reply to
376 be sent. Returns 1 on success or the Lua constant "nil" on
377 failure.
378 odkim.sig_bhresult(sig)
380 Returns the result code corresponding to the body hash evalua‐
381 tion of the signature handled specified by sig, previously
382 returned by a call to odkim.get_sighandle(). Valid values are
383 the DKIM_SIGBH_* constants defined in the libopendkim header
384 file dkim.h.
385 odkim.sig_bodylength(sig)
387 Returns the total length of the message signed by sig, previ‐
388 ously returned by a call to odkim.get_sighandle(), or the Lua
389 constant "nil" if this value could not be determined.
390 odkim.sig_canonlength(sig)
392 Returns the canonicalized length of the message signed by sig,
393 previously returned by a call to odkim.get_sighandle(), or the
394 Lua constant "nil" if this value could not be determined. Note
395 that this may be less than the value returned by
396 odkim.get_bodylength() if the signature only covered part of the
397 message.
398 odkim.sig_result(sig)
400 Returns the result code corresponding to the signature handled
401 specified by sig, previously returned by a call to
402 odkim.get_sighandle(). Valid values are the constants with
403 DKIM_SIGERROR_ prefixes as defined in the libopendkim header
404 file dkim.h.
405
407 This man page covers version 2.11.0 of OpenDKIM.
408
410 Copyright (c) 2009-2015, The Trusted Domain Project. All rights
411 reserved.
412
414 opendkim(8), opendkim.conf(5)
415 Lua -- http://www.lua.org
417 The Trusted Domain Project opendkim-lua(3)