dwww Home | Manual pages | Find package

opendkim-lua(3)             Library Functions Manual            opendkim-lua(3)

NAME
       opendkim-lua - Programming the OpenDKIM filter using Lua scripts

DESCRIPTION
       The  OpenDKIM  filter  has hooks to run user-provided scripts for making
       policy decisions regarding signatures to add  on  outbound  messages  or
       verification  and  acceptance  of  messages inbound.  The hooks take the
       form of multiple Lua scripts which, if defined,  are  run  at  important
       points during processing of a message.

       For a full description of the Lua language, consult Lua programming ref-
       erences  (see below for a starting point).  This man page only describes
       the use of Lua in the context of OpenDKIM,  specifically  the  functions
       and  global  variables  OpenDKIM  provides  for  use in user-constructed
       scripts beyond what Lua provides by default.

       Unless otherwise noted, all functions described below  return  a  single
       result; on success they return the requested data, and on error they re-
       turn the Lua constant "nil".

       Four scripting hooks are provided.  They are as follows:

       setup  The  setup  script  is run after all headers for the message have
              been received but before any DKIM operations  have  started.   At
              this  point  the  user can examine the available header fields to
              decide whether the message should be signed or verified (or both)
              and, if signing, which key(s) should be used  to  add  signatures
              and which signature features are desired.

       screen The  screen script is run after the DKIM verification context has
              been established.  The main purpose of this script is to give the
              user an opportunity to examine the message header fields compared
              to the available DKIM signatures and  determine  which,  if  any,
              should  be  ignored  during  verification.  For example, the user
              might decide only signatures added by  domains  exactly  matching
              that  in  the From: domain are acceptable, and the rest should be
              ignored.

       statistics
              The statistics script is run after all of the  DKIM  verification
              and  signing work has been completed but before any final message
              handling is done.  The main purpose of this script is to give the
              user an opportunity to examine the message or its signatures  and
              make arbitrary additional statistical observations that should be
              recorded by the statistics module.  (Experimental feature not en-
              abled for this installation.)

       final  The  final  script  is run after all of the DKIM verification and
              signing work has been completed.  The user has an opportunity  to
              examine  the results of all of the signature evaluations and make
              a decision about whether or not the message should  be  accepted,
              rejected,  discarded,  quarantined,  etc.   If the message is ac-
              cepted, any signatures requested earlier will  be  added  to  the
              messages before it is released.

GLOBAL VARIABLES
       The following global variable(s) are provided for all user scripts:

       ctx    This  is  a  generic  context pointer referring to the context in
              which the filtering operation is being performed.  It  represents
              a  single  message  in progress, and the connection that accepted
              it.

SETUP SCRIPT FUNCTIONS
       These functions are made available  to  Lua  for  processing  a  message
       through the setup script:

       odkim.check_popauth(ctx)
              Returns 1 if the SMTP client represented by ctx is coming from an
              IP  address found in the POPAUTH database (if enabled and config-
              ured), and 0 otherwise.  Returns the Lua constant  "nil"  if  the
              POPAUTH database is not enabled or not configured.

       odkim.db_check(db, string)
              Returns  1  if  db  refers  to  a  valid database handle (see od-
              kim.get_dbhandle() below) and string is found in  that  database,
              and  0  otherwise.  If an error occurs, the Lua constant "nil" is
              returned.

       odkim.db_close(db)
              Closes the specified data set.  Returns 1.  The current implemen-
              tation will conduct data set garbage collection when  the  script
              terminates,  so  this  is  not  strictly necessary, but is recom-
              mended.

       odkim.db_open(name[, icase])
              Opens the data set specified by name.  If icase is  provided  and
              is  "true",  then queries into the database will be case-insensi-
              tive.  See the opendkim(8) man page for information on specifying
              a data set.  On success, returns a handle that can be  passed  to
              odkim.db_check(); raises an exception on failure.

       odkim.export(ctx, name, value[, name2, value2[, ...]])
              Exports  variables  named with their corresponding values so that
              they will be available to later scripts.

       odkim.get_clienthost(ctx)
              Returns the name of the host on the other end of the SMTP connec-
              tion sending the current message.  This is  usually  a  hostname,
              but  might  be  an  IP  address  in  square  brackets if the SMTP
              client's IP address does not have a name associated with it.

       odkim.get_clientip(ctx)
              Returns the IP address of the client on the other end of the SMTP
              connection sending the current message as a  string.   Both  IPv4
              and IPv6 addresses are supported.

       odkim.get_dbhandle(ctx, db)
              Returns  a  handle for the requested database that can be used in
              later queries.  The value of db should be one of  DB_MTAS  (data-
              base  of MTA names whose mail should be signed), DB_MACROS (data-
              base of MTA macro checks to be done  when  determining  signing),
              DB_DOMAINS  (database  of  domains to be signed), DB_SIGNINGTABLE
              (database of signing table entries), DB_THIRDPARTY  (database  of
              third party signatures to be trusted) and DB_DONTSIGNTO (database
              of recipients whose mail should not be signed).  If the requested
              database  is  not  set  in  the current configuration file, a Lua
              "nil" is returned.

       odkim.get_envfrom(ctx)
              Retrieves the SMTP envelope sender address for the message repre-
              sented by ctx.

       odkim.get_fromdomain(ctx)
              Retrieves the domain name of the sender  of  the  message  repre-
              sented by ctx.

       odkim.get_header(ctx, name, n)
              Retrieves  the string contained in instance n of the header field
              called name from the message represented by ctx, or the Lua  con-
              stant "nil" if there was no such header field.  Header field num-
              bering  starts  at  0, so use 0 for the first instance, 1 for the
              second, etc.  For example:

              fromaddr = odkim.get_header(ctx, "From", 0)

              This will return the value of  the  first  (and  hopefully  only)
              "From"  header  field.  Negative values of n count backwards from
              the end of the set of header fields, so:

              rcvd = odkim.get_header(ctx, "Received", -2)

              will retrieve the second-last Received: header field on the  mes-
              sage.

       odkim.get_mtasymbol(ctx, name)
              Retrieves  the  value of the symbol called name from the MTA con-
              nection represented by ctx, or the Lua constant "nil" if the  re-
              quested symbol was not available at the time of the request.

       odkim.get_rcpt(ctx, n)
              Returns the nth envelope recipient for the message represented by
              ctx.   Recipient  numbering starts at 0, so for the first recipi-
              ent, use 0 for n.  If n references an out-of-range value, the Lua
              constant "nil" is returned.

       odkim.get_rcptarray(ctx)
              Returns the envelope recipients for the  message  represented  by
              ctx in a single Lua array.

       odkim.internal_ip(ctx)
              Returns  1  if  the SMTP client is coming from an internal IP ad-
              dress, and 0 otherwise.

       odkim.log(ctx, log)
              Logs the string log if the current configuration  requested  log-
              ging.   (Checking  current configuration is why the ctx parameter
              is required.)

       odkim.rcpt_count(ctx)
              Returns the count of envelope recipients on the message.

       odkim.replace_header(ctx, name, n, newval)
              Retrieves the value of in instance n of header field name in  the
              message referenced by ctx and replaces it with the string in new-
              val.   See  odkim.get_header()  above  for more information about
              possible parameter values for n.  Note that this only changes the
              content of the header field used when generating or verifying the
              signature; the actual delivered message is  not  modified.   This
              can be used to anticipate how an intermediate mail transfer agent
              might  alter  the message, thus correcting an avoidable signature
              invalidation.

       odkim.resign(ctx)
              Arranges that the arriving message will be verified and then  re-
              signed  in  a  single operation.  Returns 1 on success or the Lua
              constant "nil" on failure.

       odkim.set_result(ctx, result)
              Arranges to have the MTA return a specific  result  code  in  re-
              sponse  to  the  message represented by ctx.  The value of result
              must be one of SMFIS_TEMPFAIL (temporary failure/rejection),  SM-
              FIS_ACCEPT  (accept  without  further  processing), SMFIS_DISCARD
              (accept but discard  the  message)  and  SMFIS_REJECT  (permanent
              failure/rejection).   Returns  1  on  success or the Lua constant
              "nil" on failure.  Note that returning any of these  codes  indi-
              cates  a  final message disposition; the MTA will be told immedi-
              ately to take the specified action, and no  further  filter  pro-
              cessing will occur.

       odkim.sign(ctx[, keyname[, signer[, signlen]]])
              Requests  that the filter sign the message represented by ctx us-
              ing the specified keyname.  The key name will be translated  into
              an  actual  domain,  selector  and private key via a query to the
              KeyTable (see the opendkim.conf(5) page for details).   The  key-
              name  may  be omitted if the KeyTable is not defined, meaning the
              single signing domain, selector and key should be used  to  sign.
              Returns 1 on success and 0 on failure.  If a signer is specified,
              the  string  there  will be included in the generated signature's
              "i=" tag.  If a signlen is specified, the  signature  will  cover
              that many bytes of the message body.  The order of these last two
              parameters is interchangeable.

       odkim.signfor(ctx, address[, multi])
              Applies  whatever  signatures  would be applied by default if the
              candidate message had the  specified  address  in  the  message's
              From:   field.   The  multi  parameter,  if  "true"  (default  is
              "false"), allows the application of multiple signatures.  Returns
              the number of signatures applied, which may be zero.

       odkim.spam(ctx)
              Tags the message as spam, for use in developing reputation  about
              domains that signed the message.  Returns nothing.  (Experimental
              feature not enabled for this installation.)

       odkim.use_ltag(ctx)
              Requests  that all signatures added to the message represented by
              ctx include "l=" (body length) tags.  Always returns the Lua con-
              stant "nil".

       odkim.verify(ctx)
              Requests that the message represented by ctx be subjected to DKIM
              signature verification.  Returns the Lua constant "nil"  on  suc-
              cess, or an error string on failure.

       odkim.xtag(ctx, tag, value)
              Requests  that all signatures added to the message represented by
              ctx include the named extension tag and value.  Returns the  num-
              ber  of signatures successfully modified, or -1 on error.  An er-
              ror can occur if the named tag is  one  already  explicitly  sup-
              ported  by the DKIM library, or if there is a syntax error in the
              tag or value.

SCREEN SCRIPT FUNCTIONS
       The screen script has the following functions available to it, whose de-
       scriptions can  be  found  above:  odkim.db_check,  odkim.db_close,  od-
       kim.db_open,  odkim.export,  odkim.get_dbhandle,  odkim.get_envfrom, od-
       kim.get_fromdomain,    odkim.get_header,    odkim.get_mtasymbol,     od-
       kim.get_rcpt,  odkim.get_rcptarray,  odkim.internal_ip,  odkim.log,  od-
       kim.rcpt_count, and odkim.spam.

       The following additional functions are provided for this script:

       odkim.get_sigarray(ctx)
              Returns the complete set of signature handles found in  the  mes-
              sage  represented  by  ctx,  as  a Lua array, or the Lua constant
              "nil" in case of an error.

       odkim.get_sigcount(ctx)
              Returns the number of signatures found in the message represented
              by ctx, or the Lua constant "nil" in case of an error.

       odkim.get_sighandle(ctx, n)
              Returns a handle representing an internal copy of the nth  signa-
              ture found on the message represented by ctx.  n must be a number
              greater  than or equal to zero (representing the first signature)
              and less than the number of signatures on the message, which  can
              be determined using odkim.get_sigcount above.  The requested han-
              dle is returned on success, or the Lua constant "nil" is returned
              on failure.

       odkim.parse_field(string)
              Parses  the  contents of a header field, provided as string, into
              user and domain parts, discarding whitespace and  comment  compo-
              nents.   Returns  two strings, the user part and the domain part,
              or the Lua constant "nil" in case of a parsing error.

       odkim.sig_getdomain(sig)
              Returns the name of the domain in the signature handle  specified
              by  sig,  previously returned by a call to odkim.get_sighandle().
              This is taken from the signature's "d=" tag.

       odkim.sig_getidentity(sig)
              Returns the identity of the agent  adding  the  signature  handle
              specified   by   sig,  previously  returned  by  a  call  to  od-
              kim.get_sighandle().  This is taken  from  the  signature's  "i="
              tag.  This may be a default value and not one that was explicitly
              part  of the signature.  If the identity could not be determined,
              the Lua constant "nil" is returned.

       odkim.sig_ignore(sig)
              Instructs the verification code to ignore completely  the  signa-
              ture  specified  by  sig,  previously  returned  by a call to od-
              kim.get_sighandle().  Any pending  verification  of  the  message
              will  act  as  if  that signature was not present on the message.
              Always returns the Lua constant "nil".

STATISTICS SCRIPT FUNCTIONS
       The statistics script has the following functions available to it, whose
       descriptions can be found above:  odkim.export,  odkim.get_envfrom,  od-
       kim.get_header,  odkim.get_mtasymbol,  odkim.get_rcpt, odkim.get_rcptar-
       ray, odkim.get_sigarray,  odkim.get_sigcount,  odkim.get_sighandle,  od-
       kim.internal_ip,  odkim.log,  odkim.parse_field,  odkim.rcpt_count,  od-
       kim.sig_getdomain, odkim.sig_getidentity, and odkim.spam.

       The following functions are also available, defined in the next section:
       odkim.rbl_check,     odkim.rcpt_count,      odkim.sig_bhresult,      od-
       kim.sig_bodylength, odkim.sig_canonlength, and odkim.sig_result.

       The following additional function is provided for this script:

       odkim.stats(ctx, name, value)
              Records  the additional statistic called name with its associated
              value for the message represented by ctx.

FINAL SCRIPT FUNCTIONS
       The final script has the following functions available to it, whose  de-
       scriptions can be found above: odkim.get_clienthost, odkim.get_clientip,
       odkim.get_envfrom,     odkim.get_fromdomain,    odkim.get_header,    od-
       kim.get_mtasymbol, odkim.get_rcpt, odkim.get_rcptarray, odkim.get_sigar-
       ray,  odkim.get_sigcount,  odkim.get_sighandle,  odkim.internal_ip,  od-
       kim.log,   odkim.parse_field,  odkim.rcpt_count,  odkim.set_result,  od-
       kim.sig_getdomain, odkim.sig_getidentity, odkim.spam, and odkim.xtags.

       The following additional functions are provided for this script:

       odkim.add_header(ctx, name, value)
              Adds a new header field called name with the specified  value  to
              the message represented by ctx.  Returns 1 on success, or the Lua
              constant "nil" on failure.

       odkim.add_rcpt(ctx, addr)
              Adds  addr as an envelope recipient to the message represented by
              ctx.  Returns 1 on success, or the Lua constant "nil" on failure.

       odkim.del_header(ctx, name, n)
              Deletes the nth instance (starting from 0) of  the  header  field
              called  name  from  the message represented by ctx.  Returns 1 on
              success, or the Lua constant "nil" on failure.

       odkim.del_rcpt(ctx, addr)
              Deletes addr from the list of envelope recipients on the  message
              represented  by  ctx, and adds a new X-Original-Recipient: header
              field containing the deleted address.  Returns 1 on  success,  or
              the Lua constant "nil" on failure.

       odkim.quarantine(ctx, reason)
              Asks  the  MTA to quarantine the message represented by ctx using
              reason as a text string indicating the reason  for  the  request.
              Returns 1 on success or the Lua constant "nil" on failure.

       odkim.rbl_check(ctx, query, qroot[, timeout])
              Makes  an  RBL  query.   The  root of the RBL is assumed to be at
              qroot and the subject of the query is query, so  the  query  per-
              formed will be query.qroot .  The context handle ctx must also be
              provided  as it contains a handle to the established DNS service.
              The optional timeout parameter is the timeout to use, in seconds.
              Returns "nil" on error, no values if the requested record was not
              present in the RBL, or the four octets of the  RBL  entry  if  it
              was.   The  octets are returned in big-endian order.  (Note: Fea-
              ture is experimental.)

       odkim.set_reply(ctx, rcode, xcode, message)
              Instructs the MTA to return  the  specified  SMTP  reply  to  the
              client  sending  the message represented by ctx.  rcode must be a
              three-digit SMTP reply code starting with 4 or 5  (for  temporary
              or  permanent  failures,  respectively);  xcode must be the empty
              string or a valid extended  reply  code  (see  RFC2034)  matching
              rcode;  and message must be the text portion of the SMTP reply to
              be sent.  Returns 1 on success or the Lua constant "nil" on fail-
              ure.

       odkim.sig_bhresult(sig)
              Returns the result code corresponding to the body hash evaluation
              of the signature handled specified by sig, previously returned by
              a  call  to  odkim.get_sighandle().    Valid   values   are   the
              DKIM_SIGBH_*  constants  defined  in  the libopendkim header file
              dkim.h.

       odkim.sig_bodylength(sig)
              Returns the total length of the message signed by sig, previously
              returned by a call to odkim.get_sighandle(), or the Lua  constant
              "nil" if this value could not be determined.

       odkim.sig_canonlength(sig)
              Returns  the  canonicalized  length of the message signed by sig,
              previously returned by a call to  odkim.get_sighandle(),  or  the
              Lua  constant  "nil" if this value could not be determined.  Note
              that  this  may  be  less  than  the  value   returned   by   od-
              kim.get_bodylength()  if  the  signature only covered part of the
              message.

       odkim.sig_result(sig)
              Returns the result code corresponding to  the  signature  handled
              specified   by   sig,  previously  returned  by  a  call  to  od-
              kim.get_sighandle().   Valid  values  are  the   constants   with
              DKIM_SIGERROR_ prefixes as defined in the libopendkim header file
              dkim.h.

VERSION
       This man page covers version 2.11.0 of OpenDKIM.

COPYRIGHT
       Copyright  (c)  2009-2015,  The  Trusted Domain Project.  All rights re-
       served.

SEE ALSO
       opendkim(8), opendkim.conf(5)

       Lua -- http://www.lua.org

                           The Trusted Domain Project           opendkim-lua(3)

Generated by dwww version 1.16 on Thu Nov 19 22:57:02 CET 2026.