# OpenDMARC Library (libopendmarc)

## Introduction

DMARC stands for "Domain-based Message Authentication, Reporting & Conformance". It is a technical specification created by a group of organizations to help reduce the potential for email-based abuse by solving long-standing operational, deployment, and reporting issues related to the existing email authentication protocols of DKIM and SPF. More information about DMARC can be found at the dmarc.org website.

This API (`libopendmarc`) at its current release, allows an application to look up DMARC records and to apply policy to application supplied DKIM and SPF results. An implementation of a filter, using Sendmail's milter package, uses this `libopendmarc` library.

## Data Types

Data Type | Description
`OPENDMARC_LIB_T` | The structure used to initialize the library at startup
`DMARC_POLICY_T` | The context used per in-bound envelope.
`OPENDMARC_STATUS_T` | The type returned by many library functions.

## Functions

Function | Description
Program Startup/Shutdown
`opendmarc_policy_library_init()` | Initialize the library on program startup.
`opendmarc_policy_library_shutdown()` | Shut down the library to free resources.
Per-Envelope Context Functions
`opendmarc_policy_connect_init()` | Allocate a new context for an in-bound envelope.
`opendmarc_policy_connect_clear()` | Clears (zeros) a context for reuse.
`opendmarc_policy_connect_rset()` | Partially clears the context as part of an SMTP RSET.
`opendmarc_policy_connect_shutdown()` | Deallocate and free a context to conclude its use.
Information Storage Functions
`opendmarc_policy_store_from_domain()` | Give the policy processor the From: header's domain.
`opendmarc_policy_store_dkim()` | Give the policy processor the results of DKIM processing.
`opendmarc_policy_store_spf()` | Give the policy processor the results of SPF processing.
DMARC Record Functions
`opendmarc_policy_query_dmarc()` | DNS lookup a DMARC record and parse it.
`opendmarc_policy_parse_dmarc()` | Parse a user supplied DMARC record.
`opendmarc_policy_store_dmarc()` | The user process looked up the DMARC record and provides it to the library in one gulp.
DMARC Result Functions
`opendmarc_get_policy_to_enforce()` | Returns the policy for the MTA to enforce.
`opendmarc_policy_fetch_pct()` | Fetch the value of the pct= DMARC setting to determine sampling rate.
`opendmarc_policy_fetch_adkim()` | Fetch the value of the adkim= DMARC setting to determine alignment policy.
`opendmarc_policy_fetch_aspf()` | Fetch the value of the aspf= DMARC setting to determine alignment policy.
`opendmarc_policy_fetch_p()` | Fetch the value of the p= DMARC setting to determine desired policy.
`opendmarc_policy_fetch_sp()` | Fetch the value of the sp= DMARC setting to determine desired subdomain policy.
`opendmarc_policy_fetch_rua()` | Fetch a list of the rua= DMARC URI stating where to send reports.
`opendmarc_policy_fetch_ruf()` | Fetch a list of the ruf= DMARC URI stating where to send failed messages notifications.
`opendmarc_policy_fetch_fo()` | Fetch a bitmap that shows how/when that RUF reports should be sent.
`opendmarc_policy_fetch_rf()` | Fetch a bitmap that shows which format (arfrf versus iodef) should be used.
`opendmarc_policy_fetch_alignment()` | Fetch the result of SPF and DKIM alignment checks.
`opendmarc_policy_fetch_utilized_domain()` | Fetch the domain that was used to find the DMARC record.
TLD Functions
`opendmarc_tld_read_file()` | Read and re-read a `TLD` file for library use. (See also `opendmarc_policy_library_init()`)
`opendmarc_tld_shutdown()` | Deallocate the cached `TLD` information as part of program shutdown.
XML File Functions
`opendmarc_xml()` | Parse an XML Report file that was read into a memory buffer and produce CSV output.
`opendmarc_xml_parse()` | Read an XML Report file from disk and parse it into CSV output.
SPF Checking Functions
`opendmarc_spf_test.html()` | Look up an SPF record and determine if it is a pass or fail.
Handy Utility Functions
`opendmarc_dns_fake_record()` | Hard-code some DNS replies. Intended for use during unit tests.
`opendmarc_util_clearargv()` | Free a NULL terminated array of strings.
`opendmarc_policy_status_to_str()` | Fetch a human readable string correspoding to a `OPENDMARC_STATUS_T` value returned by a function.
`opendmarc_policy_to_buf()` | Fetch a human readable copy of the opaque `DMARC_POLICY_T` into a text buffer.

Copyright (c) 2012, 2014, The Trusted Domain Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the license.