OPENARC.CONF(5)

NAME
openarc.conf - Configuration file for openarc

LOCATION
/usr/pkg/etc/openarc.conf

DESCRIPTION
openarc(8) implements the ARC (Authenticated Received Chain) specification for verifying authentication and handling of messages as they are routed to their destinations. This is its configuration file.

Blank lines are ignored. Lines containing a hash ("#") character are truncated at the hash character to allow for comments in the file.

Other content should be the name of a parameter, followed by white space, followed by the value of that parameter. Each parameter must be on a separate line.

For parameters that are Boolean in nature, only the first byte of the value is processed. For positive values, the following are accepted: T, t, Y, y, 1.

For negative values, the following are accepted: F, f, N, n, 0.

See the openarc(8) man page for details about how and when the configuration file contents are reloaded.

Unless otherwise stated, boolean values default to false, integer values default to 0, and string and dataset values default to being undefined.

PARAMETERS

AuthResComments (boolean)
    Controls whether Authentication-Results headers include any comments parsed from the previously existing headers.

AuthResIP (boolean)
    Controls whether Authentication-Results headers include the remote IP. The default is true.

AuthservID (string)
    authserv-id to use in Authentication-Results headers.

AutoRestart (boolean)
    Automatically re-start on failures. Use with caution; if the filter fails instantly after it starts, this can cause a tight fork(2) loop.

AutoRestartCount (integer)
    Sets the maximum automatic restart count. After this number of automatic restarts, the filter will give up and terminate. A value of 0 implies no limit; this is the default.

AutoRestartRate (string)
    Sets the maximum automatic restart rate. If the filter begins restarting faster than the rate defined here, it will give up and terminate. This is a string of the form n/t[u] where n is an integer limiting the count of restarts in the given interval and t[u] defines the time interval through which the rate is calculated; t is an integer and u defines the units thus represented ("s" or "S" for seconds, the default; "m" or "M" for minutes; "h" or "H" for hours; "d" or "D" for days). For example, a value of "10/1h" limits the restarts to 10 in one hour. There is no default, meaning restart rate is not limited.

Background (boolean)
    Causes openarc(8) to fork and exit immediately, leaving the service running in the background. The default is true.

BaseDirectory (string)
    Directory to switch to before beginning operation.

Canonicalization (string)
    Selects the canonicalization method(s) to be used when signing messages. When verifying, the message's ARC-Message-Signature: header field specifies the canonicalization method. The recognized values are relaxed and simple as defined by the DKIM specification. The default is relaxed/simple. The value may include two different canonicalizations separated by a slash ("/") character, in which case the first will be applied to the header and the second to the body.

ChangeRootDirectory (string)
    Requests that the operating system change the effective root directory of the process to the one specified here prior to beginning execution. chroot(2) requires superuser access. A warning will be generated if UserID is not also set.

Domain (string)
    Domain to use when signing messages. Required for signing.

EnableCoredumps (boolean)
    On systems that have such support, make an explicit request to the kernel to dump cores when the filter crashes for some reason. Some modern UNIX systems suppress core dumps during crashes for security reasons if the user ID has changed during the lifetime of the process. Currently only supported on Linux.

FinalReceiver (boolean)
    Add a non-standard arc.chain field to the Authentication-Results header, showing the domains present in the ARC chain.

FixedTimestamp (string)
    Used for testing. This is not useful in a production environment.

Include (string)
    Names a file to be opened and read as an additional configuration file. Nesting is allowed to a maximum of five levels.

InternalHosts (dataset)
    Identifies a set of hosts whose connections should be treated as "internal" by this filter. Messages received from such sources will not be verified and are instead trusted as-is; in particular, their Authentication-Results fields are trusted to be correct and authentic, meaning they will be assumed to contain the correct chain status when generating an outgoing seal. See the description of "PeerList" for a description of the supported format. If no set is provided, "127.0.0.1" is added to the list by default.

KeepTemporaryFiles (boolean)
    Preserve temporary files generated during signing or verification for debugging purposes. This can use up disk space very quickly on busy systems.

KeyFile (string)
    Path to the private key to use when signing. Required for signing.

MaximumHeaders (integer)
    Disable processing for messages where the header section is larger than this value (in bytes.) 0 disables this check, the default is 65536.

MilterDebug (integer)
    Sets the debug level to be requested from the milter library. The default is 0.

MinimumKeySizeRSA (integer)
    Disallows signatures whose keys are smaller than the specified size, regardless of whether they would otherwise be valid. If this is not set the library's default (which is currently 1024) will be used.

Mode (string)
    Selects the operating mode(s) for this filter. If the string contains the character "s", the filter will seal messages passing through the filter by adding a new ARC set. If the string contains the character "v", the filter will validate existing ARC sets and record the chain validation status in an "Authentication-Results" header. The two can be combined. If neither is specified, the operating mode will be inferred on a per-connection basis based on the entries in the InternalHosts list; connections from internal hosts will be assigned to signing mode, and all others will be assigned to verify mode.

OversignHeaders (string)
    Specifies a comma-separated list of header field names that should be included in all signature header lists (the "h=" tag) once more than the number of times they were actually present in the signed message. The set is empty by default. The purpose of this, and especially of listing an absent header field, is to prevent the addition of important fields between the signer and the verifier. Since the verifier would include that header field when performing verification if it had been added by an intermediary, the signed message and the verified message were different and the verification would fail. Note that listing a field name here and not listing it in the SignHeaders list is likely to generate invalid signatures.

PeerList (dataset)
    Identifies a set of "peers" that identifies clients whose connections should be accepted without processing by this filter. The set should contain on each line a hostname, domain name (e.g. ".example.com"), IP address, an IPv6 address (including an IPv4 mapped address), or a CIDR-style IP specification (e.g. "192.168.1.0/24"). An entry beginning with a bang ("!") character means "not", allowing exclusion of specific hosts that are otherwise members of larger sets. Host and domain names are matched first, then the IP or IPv6 address depending on the connection type. More precise entries are preferred over less precise ones, e.g. "192.168.1.1" will match before "!192.168.1.0/24". The text form of IPv6 addresses will be forced to lowercase when queried (RFC5952), so the contents of this data set should also use lowercase. The IP address portion of an entry may optionally contain square brackets; both forms (with and without) will be checked.

PermitAuthenticationOverrides (boolean)
    Controls whether a previous Authentication-Result with the same authserv-id is allowed to override the computed ARC chain validation status. The default is false because this can be unsafe unless you have taken steps to ensure that the Authentication-Result headers seen by the filter are legitimate.

PidFile (string)
    Specifies the path to a file that should be created at process start containing the process ID.

RequireSafeKeys (boolean)
    Controls whether the filter requires that private keys have safe file permissions. The default is true.

ResponseDisabled (string)
    {accept | discard | reject | tempfail} Response to send after determining that this message is one that the filter is configured not to process. See SealHeaderChecks and PeerList. The default is accept.

ResponseUnable (string)
    {accept | discard | reject | tempfail} Response to send after an internal error occurs that makes it impossible to finish processing the message. The default is tempfail.

ResponseUnwilling (string)
    {accept | discard | reject | tempfail} Response to send after a message fails basic validity checks, such as MaximumHeaders. The default is reject.

SealHeaderChecks (string)
    Identifies a file containing header checks that should be done to determine whether to seal a message. Each entry in this file must be of the form name:regexp. When this feature is set, messages will only be processed by the filter if any instance of the named header field exists and has a value matching the provided regular expression. If the value of an instance appears to be a JSON list, then the regular expression is applied to all strings in the list.

Selector (string)
    Selector to use when signing messages. Required for signing.

SignatureAlgorithm (string)
    Selects the signing algorithm to use when generating signatures. Use ‘openarc -V’ to see the list of supported algorithms. The default is rsa-sha256. Other values are not useful if you are intending to interoperate with other implementers of the ARC protocol.

SignatureTTL (integer)
    Specifies the amount of time (in seconds) before generated signatures expire. The default is 0, for no expiration. You probably should not set this below 604800 in production deployments.

SignHeaders (string)
    Specifies the set of header fields that should be included when generating signatures. This is expected to be a comma-separated list of header field names, and matching is case-insensitive. If the list omits any header field that is mandated by the ARC specification, those fields are implicitly added. By default, those fields listed in the DKIM specification as "SHOULD" be signed (RFC6376, Section 5.4) will be signed by the filter.

Socket (string)
    Specifies the socket that should be established by the filter to receive connections from the MTA. socketspec is in one of two forms: local:path, which creates a UNIX domain socket at the specified path, or inet:port[@host] or inet6:port[@host] which creates a TCP socket on the specified port and in the specified protocol family. If the host is not given as either a hostname or an IP address, the socket will be listening on all interfaces. A literal IP address must be enclosed in square brackets. This option is mandatory either in the configuration file or on the command line.

SoftwareHeader (boolean)
    Add an ARC-Filter header advertising the filter name and version.

Syslog (boolean)
    Log interesting activity to syslog(3).

SyslogFacility (string)
    Use the named facility when logging via syslog(3). The default is mail.

TemporaryDirectory (string)
    Directory to use when creating temporary files. The default is /tmp

TestKeys (string)
    Used for testing. Name of a file containing static DKIM records that will be used for validation instead of live DNS lookups, one per line. This is not useful in a production environment.

UMask (integer)
    Requests a specific permissions mask to be used for file creation. This only applies to creation of the socket when Socket specifies a UNIX domain socket, and to the PidFile (if any). See umask(2) for more information.

UserID (string)
    Attempts to become the specified userid before starting operations. The value is of the form userid[:group]. The process will be assigned all of the groups and primary group ID of the named userid unless an alternate group is specified.

SEE ALSO

openarc(8)

sendmail(8)