Authenticated Received Chain - ARC-sealing

README.adoc

@@ -1,88 +1,112 @@
-= JAMES jDKIM library
+= JAMES jDKIM fork with ARC support
 
+This repository is a fork of Apache James jDKIM that adds ARC (Authenticated Received Chain) signing and related mail authentication capabilities alongside
+the original DKIM functionality.
 
-Library dealing with parsing and crytography to sign and verify DKIM signatures.
+It is intended for experimentation and integration work around RFC 8617 in Java-based mail processing workflows.
+
+Original upstream project:
+https://github.com/apache/james-jdkim
 
 The mailet has been moved to James project: https://github.com/apache/james-project/tree/master/server/mailet/dkim
 
+== Fork-specific additions
+
+This fork extends the original Apache James jDKIM codebase with ARC-related functionality.
+
+Current fork-specific focus includes:
+
+- ARC signing support
+- ARC chain handling
+- Mail authentication extensions related to RFC 8617
+
+== 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.
+
 == Usage
 
 A full example is available in
-https://github.com/apache/james-jdkim/blob/master/main/src/test/java/org/apache/james/jdkim/DKIMTest.java[DKIMTest]
+https://github.com/apache/james-jdkim/blob/master/arc/src/test/java/org/apache/james/arc/ARCTest.java[ARCTest]
 
-=== Signing
+=== Building An ARC Set
 
-Signing a mime message can be achieved using the following snippet
+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 signatureTemplate = "v=1; a=rsa-sha256; c=simple; d=messiah.edu; h=date:from:subject; q=dns/txt; s=selector2;";
+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;
-DKIMSigner dkimSigner = new DKIMSigner(signatureTemplate, privateKey);
-// You need to provide the input stream of the mime message, it will be parsed
-// by mime4j
 InputStream stream = null;
-String signature = dkimSigner.sign(inputStream);
-// `signature` contains the full header
-// DKIM-Signature: a=rsa-sha256; q=dns/txt; b=Axa8s/g...U1SIw==; c=simple; s=selector2; d=messiah.edu; v=1; bh=6pQ...6g=; h=date:from:subject;
+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");
 ----
 
-More advanced usage such as including multiple signatures can be found in
-https://github.com/apache/james-jdkim/blob/master/main/src/test/java/org/apache/james/jdkim/DKIMTest.java[DKIMTest]
+The generated map contains the ARC headers for the current hop, ready to be
+added to the message.
+
+More complete usage can be found in
+https://github.com/apache/james-jdkim/blob/master/arc/src/test/java/org/apache/james/arc/ARCTest.java[ARCTest]
 
-=== Verifying
+=== Validating An ARC Chain
 
-Verifying a mime message DKIM signatures can be achieved using the following
-snippet. The verifier always verifies all the signatures.
+Validating ARC headers on a MIME message can be achieved using the following
+snippet.
 
 [source,java]
 ----
 import java.io.InputStream;
-// You can override the resolver in the constructor, use your own
-// implementation of a retriever or use multiple implementations using a
-// `MultiplexingPublicKeyRecordRetriever`
-PublicKeyRecordRetriever keyRecordRetriever = new DNSPublicKeyRecordRetriever();
-DKIMVerifier verifier = new DKIMVerifier(keyRecordRetriever);
-InputStream stream = null; // you need to provide the input stream of the mime message
-List<SignatureRecord> verifiedSignatures = verifier.verify(stream);
-// `verifiedSignatures` contains only the signatures that have successfully
-// passed the validation.
-// If you want to query all the results including all the failures, you can
-// retrieve them from the verifier
-List<Result> results = verifier.getResults();
-----
+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);
 
-== Cryptography Notice
+ARCChainValidator arcChainValidator = new ARCChainValidator(keyRecordRetriever);
+ArcValidationOutcome validation = arcChainValidator.validateArcChain(message);
 
+boolean valid = validation.isValid();
+String chainValidation = validation.getResult().toString();
 ----
-   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 
-   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 
-   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 
-   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>