Authenticated Received Chain - ARC-sealing

README.adoc

@@ -1,7 +1,9 @@
 = JAMES jDKIM library
 
 
-Library dealing with parsing and crytography to sign and verify DKIM signatures.
+Library dealing with parsing and cryptography to sign and verify DKIM signatures.
+It also provides DMARC verification and ARC (Authenticated Received Chain)
+support for Java-based mail processing workflows.
 
 The mailet has been moved to James project: https://github.com/apache/james-project/tree/master/server/mailet/dkim
 
@@ -56,33 +58,154 @@ List<SignatureRecord> verifiedSignatures = verifier.verify(stream);
 List<Result> results = verifier.getResults();
 ----
 
+=== Checking DMARC
+
+DMARC verification combines SPF and DKIM results with the RFC5322 `From`
+domain and the domain DMARC policy.
+
+[source,java]
+----
+import org.apache.james.dmarc.DMARCVerifier;
+import org.apache.james.dmarc.DmarcValidationResult;
+import org.apache.james.dmarc.PublicKeyRecordRetrieverDmarc;
+import org.apache.james.mime4j.dom.Message;
+
+PublicKeyRecordRetrieverDmarc recordRetriever = null;
+Message message = null;
+
+DMARCVerifier dmarcVerifier = new DMARCVerifier(recordRetriever);
+DmarcValidationResult dmarcResult = dmarcVerifier.runDmarcCheck(
+        message,
+        "pass client-ip=192.0.2.1; envelope-from=sender@example.org",
+        "example.org",
+        "pass",
+        "example.org");
+
+String authenticationResult = dmarcResult.toString();
+----
+
+More complete DMARC examples can be found in
+https://github.com/apache/james-jdkim/blob/master/dmarc/src/main/test/java/org/apache/james/dmarc/DMARCTest.java[DMARCTest].
+
+== ARC Support
+
+ARC support adds RFC 8617 signing and validation for intermediaries that need to
+preserve authentication results across forwarding hops.
+
+=== Building An ARC Set
+
+Generating ARC headers for a MIME message can be achieved using the following
+snippet.
+
+[source,java]
+----
+import java.io.InputStream;
+import java.security.PrivateKey;
+import java.util.Map;
+
+import org.apache.james.arc.ArcSetBuilder;
+import org.apache.james.arc.PublicKeyRetrieverArc;
+import org.apache.james.mime4j.dom.Message;
+import org.apache.james.mime4j.message.DefaultMessageBuilder;
+
+String amsTemplate = "i=; a=rsa-sha256; c=relaxed/relaxed; d=example.org; s=arc; t=; h=Subject:From:To; bh=; b=";
+String sealTemplate = "i=; cv=; a=rsa-sha256; d=example.org; s=arc; t=; b=";
+
+PrivateKey privateKey = null;
+InputStream stream = null;
+Message message = new DefaultMessageBuilder().parseMessage(stream);
+
+ArcSetBuilder arcSetBuilder = new ArcSetBuilder(
+        privateKey,
+        amsTemplate,
+        sealTemplate,
+        "mx.example.org",
+        System.currentTimeMillis() / 1000);
+
+PublicKeyRetrieverArc keyRecordRetriever = null;
+Map<String, String> arcSet = arcSetBuilder.buildArcSet(
+        message,
+        "mail.example.org",
+        "sender@example.org",
+        "192.0.2.1",
+        keyRecordRetriever);
+
+String authenticationResults = arcSet.get("Authentication-Results");
+String arcAuthenticationResults = arcSet.get("ARC-Authentication-Results");
+String arcMessageSignature = arcSet.get("ARC-Message-Signature");
+String arcSeal = arcSet.get("ARC-Seal");
+----
+
+The generated map contains the ARC headers for the current hop, ready to be
+added to the message.
+
+=== Validating An ARC Chain
+
+Validating ARC headers on a MIME message can be achieved using the following
+snippet.
+
+[source,java]
+----
+import java.io.InputStream;
+
+import org.apache.james.arc.ARCChainValidator;
+import org.apache.james.arc.ArcValidationOutcome;
+import org.apache.james.arc.PublicKeyRetrieverArc;
+import org.apache.james.mime4j.dom.Message;
+import org.apache.james.mime4j.message.DefaultMessageBuilder;
+
+PublicKeyRetrieverArc keyRecordRetriever = null;
+InputStream stream = null;
+Message message = new DefaultMessageBuilder().parseMessage(stream);
+
+ARCChainValidator arcChainValidator = new ARCChainValidator(keyRecordRetriever);
+ArcValidationOutcome validation = arcChainValidator.validateArcChain(message);
+
+String chainValidation = validation.getResult().toString();
+String description = validation.getDescription();
+----
+
+More complete ARC usage can be found in
+https://github.com/apache/james-jdkim/blob/master/arc/src/test/java/org/apache/james/arc/ARCTest.java[ARCTest].
+
+== Test Coverage
+
+ARC functionality is covered by tests in
+https://github.com/apache/james-jdkim/blob/master/arc/src/test/java/org/apache/james/arc/ARCTest.java[ARCTest].
+The coverage is based on the ARC protocol requirements from
+https://datatracker.ietf.org/doc/html/rfc8617[RFC 8617] and on the public
+https://github.com/ValiMail/arc_test_suite[ValiMail ARC test suite]. The tests
+exercise ARC set creation, chain validation, ARC-Seal verification,
+ARC-Message-Signature canonicalization, body hash handling, required tag
+validation, and malformed or tampered ARC header cases.
+
 == Cryptography Notice
 
 ----
-   This distribution includes cryptographic software.  The country in 
-   which you currently reside may have restrictions on the import, 
-   possession, use, and/or re-export to another country, of 
-   encryption software.  BEFORE using any encryption software, please 
+   This distribution includes cryptographic software.  The country in
+   which you currently reside may have restrictions on the import,
+   possession, use, and/or re-export to another country, of
+   encryption software.  BEFORE using any encryption software, please
    check your country's laws, regulations and policies concerning the
-   import, possession, or use, and re-export of encryption software, to 
+   import, possession, or use, and re-export of encryption software, to
    see if this is permitted.  See http://www.wassenaar.org for more
    information.
 
    The U.S. Government Department of Commerce, Bureau of Industry and
-   Security (BIS), has classified this software as Export Commodity 
+   Security (BIS), has classified this software as Export Commodity
    Control Number (ECCN) 5D002.C.1, which includes information security
    software using or performing cryptographic functions with asymmetric
    algorithms.  The form and manner of this Apache Software Foundation
    distribution makes it eligible for export under the License Exception
-   ENC Technology Software Unrestricted (TSU) exception (see the BIS 
-   Export Administration Regulations, Section 740.13) for both object 
+   ENC Technology Software Unrestricted (TSU) exception (see the BIS
+   Export Administration Regulations, Section 740.13) for both object
    code and source code.
 
    The following provides more details on the included cryptographic
    software:
-    		
+
     - jDKIM includes code designed to work with Java SE Security
 
     Export classifications and source links can be found
     at http://www.apache.org/licenses/exports/.
-----
+----

arc/pom.xml

@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements. See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership. The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied. See the License for the
+    specific language governing permissions and limitations
+    under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <artifactId>apache-jdkim-project</artifactId>
+        <groupId>org.apache.james.jdkim</groupId>
+        <version>0.6-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>apache-arc-library</artifactId>
+
+    <name>Apache James :: ARC</name>
+    <description>A Java implementation for the ARC specification.</description>
+    <url>http://james.apache.org/jdkim/main/</url>
+    <inceptionYear>2008</inceptionYear>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.james.jdkim</groupId>
+            <artifactId>apache-dmarc-library</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james.jdkim</groupId>
+            <artifactId>apache-dmarc-library</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james.jdkim</groupId>
+            <artifactId>apache-jdkim-library</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james.jdkim</groupId>
+            <artifactId>apache-jdkim-library</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james.jspf</groupId>
+            <artifactId>apache-jspf-resolver</artifactId>
+            <version>${jspf-resolver.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james</groupId>
+            <artifactId>apache-mime4j-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.james</groupId>
+            <artifactId>apache-mime4j-dom</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>