Provided by: opendkim_2.5.2+dfsg-1ubuntu3_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".

       Three 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_LOCALADSP (database of
              local  ADSP  overrides),  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_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.

       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.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.  (Experimental feature not enabled for this installation.)

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_fromdomain,    odkim.get_header,     odkim.get_mtasymbol,
       odkim.get_rcpt, odkim.get_rcptarray, 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_header,  odkim.get_mtasymbol,  odkim.get_rcpt,
       odkim.get_rcptarray,    odkim.get_sigarray,    odkim.get_sigcount,    odkim.get_sighandle,
       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.get_policy,
       odkim.get_reputation,      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_fromdomain,
       odkim.get_header,      odkim.get_mtasymbol,      odkim.get_rcpt,      odkim.get_rcptarray,
       odkim.get_sigarray, odkim.get_sigcount, odkim.get_sighandle, 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.get_policy(ctx)
              Returns the discovered Author Domain Signing Practices (ADSP) policy,  if  one  was
              published  and  could  be  retrieved,  or  a  code indicating what other result was
              observed.  The value will be  one  of  DKIMF_POLICY_UNKNOWN,  DKIMF_POLICY_ALL  and
              DKIMF_POLICY_DISCARDABLE,  representing  the corresponding ADSP result when a query
              was made and a result returned,  or  DKIMF_POLICY_NXDOMAIN  if  the  author  domain
              (based  on the "From:" header field) does not appear to exist, or DKIMF_POLICY_NONE
              if no query was done because a valid author  domain  signature  was  found  on  the
              message, or the Lua constant "nil" in case of some other error.

       odkim.get_reputation(ctx, sig, qroot)
              Performs  a reputation query about the message represented by ctx and the signature
              indicated by sig, the latter returned by a previous call to  odkim.get_sighandle().
              The  qroot  parameter  is  a string naming the DNS root of the published reputation
              query data, or can be the empty string to use the built-in  default.   The  integer
              result is returned on success, or "nil" on error.

       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.  (Experimental feature not enabled for this installation.)

       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.5.2 of OpenDKIM.

COPYRIGHT

       Copyright (c) 2009-2011, The OpenDKIM Project.  All rights reserved.

SEE ALSO

       opendkim(8), opendkim.conf(5)

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

                                       The OpenDKIM Project                       opendkim-lua(3)