Provided by: opendkim_2.11.0~alpha-11build1_amd64 bug

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 references (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 return 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 enabled 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 accepted,
              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 configured), 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 odkim.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 implementation will conduct
              data  set  garbage  collection  when the script terminates, so this is not strictly
              necessary, but is recommended.

       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-insensitive.  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  connection  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 (database of MTA names whose mail should be
              signed), DB_MACROS (database 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 represented by ctx.

       odkim.get_fromdomain(ctx)
              Retrieves the domain name of the sender of the message represented 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 constant "nil"  if  there  was  no  such
              header field.  Header field numbering 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 message.

       odkim.get_mtasymbol(ctx, name)
              Retrieves  the  value of the symbol called name from the MTA connection represented
              by ctx, or the Lua constant "nil" if the requested 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 recipient, 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  address,  and  0
              otherwise.

       odkim.log(ctx, log)
              Logs  the  string  log  if  the current configuration requested logging.  (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 newval.  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 response to the message
              represented by ctx.  The value of result must be one of  SMFIS_TEMPFAIL  (temporary
              failure/rejection), SMFIS_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 indicates  a  final  message  disposition;  the  MTA  will  be  told
              immediately  to  take  the  specified action, and no further filter processing will
              occur.

       odkim.sign(ctx[, keyname[, signer[, signlen]]])
              Requests that the filter sign the message represented by ctx  using  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  keyname 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 constant "nil".

       odkim.verify(ctx)
              Requests that the message  represented  by  ctx  be  subjected  to  DKIM  signature
              verification.   Returns  the  Lua  constant "nil" on success, 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 number of signatures successfully
              modified, or -1 on error.  An error can occur if  the  named  tag  is  one  already
              explicitly  supported 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 descriptions  can  be
       found     above:     odkim.db_check,    odkim.db_close,    odkim.db_open,    odkim.export,
       odkim.get_dbhandle,     odkim.get_envfrom,     odkim.get_fromdomain,     odkim.get_header,
       odkim.get_mtasymbol,  odkim.get_rcpt,  odkim.get_rcptarray,  odkim.internal_ip, odkim.log,
       odkim.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 message  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 signature  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
              handle 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 components.  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 odkim.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  signature  specified  by
              sig,   previously  returned  by  a  call  to  odkim.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,  odkim.get_header,  odkim.get_mtasymbol,
       odkim.get_rcpt,      odkim.get_rcptarray,      odkim.get_sigarray,     odkim.get_sigcount,
       odkim.get_sighandle, odkim.internal_ip,  odkim.log,  odkim.parse_field,  odkim.rcpt_count,
       odkim.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,  odkim.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  descriptions  can  be
       found      above:     odkim.get_clienthost,     odkim.get_clientip,     odkim.get_envfrom,
       odkim.get_fromdomain,     odkim.get_header,      odkim.get_mtasymbol,      odkim.get_rcpt,
       odkim.get_rcptarray,    odkim.get_sigarray,    odkim.get_sigcount,    odkim.get_sighandle,
       odkim.internal_ip,  odkim.log,  odkim.parse_field,   odkim.rcpt_count,   odkim.set_result,
       odkim.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 performed 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: Feature 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 failure.

       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
              odkim.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  odkim.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 reserved.

SEE ALSO

       opendkim(8), opendkim.conf(5)

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

                                    The Trusted Domain Project                    opendkim-lua(3)