Moved DKIM api to dedicated DkimConfig class and added feature to exclude certain headers from the default list of headers to sign

Author: bbottema

modules/core-module/src/main/java/org/simplejavamail/api/email/Email.java

@@ -4,11 +4,11 @@
 import jakarta.mail.internet.MimeMessage;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.simplejavamail.api.email.config.DkimConfig;
 import org.simplejavamail.api.internal.smimesupport.model.PlainSmimeDetails;
 import org.simplejavamail.api.mailer.config.Pkcs12Config;
 import org.simplejavamail.internal.util.MiscUtil;
 
-import java.io.File;
 import java.io.InputStream;
 import java.io.Serializable;
 import java.security.cert.X509Certificate;
@@ -17,6 +17,7 @@
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.TimeZone;
 
 import static java.lang.Boolean.TRUE;
@@ -151,25 +152,13 @@ public class Email implements Serializable {
 	 */
 	// mime message is not serializable, so transient
 	private transient final MimeMessage emailToForward;
-	
-	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(byte[], String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(File, String, String)
-	 */
-	private final byte[] dkimPrivateKeyData;
-	
-	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(File, String, String)
-	 */
-	private final String dkimSigningDomain;
+
 
 	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(File, String, String)
+	 * @see EmailPopulatingBuilder#signWithDomainKey(DkimConfig)
+	 * @see EmailPopulatingBuilder#signWithDomainKey(byte[], String, String, Set)
 	 */
-	private final String dkimSelector;
+	private DkimConfig dkimConfig;
 
 	/**
 	 * @see EmailPopulatingBuilder#signWithSmime(Pkcs12Config)
@@ -277,16 +266,8 @@ public Email(@NotNull final EmailPopulatingBuilder builder) {
 		} else {
 			returnReceiptTo = builder.getReturnReceiptTo();
 		}
-		
-		if (builder.getDkimPrivateKeyData() != null) {
-			this.dkimPrivateKeyData = builder.getDkimPrivateKeyData();
-			this.dkimSigningDomain = builder.getDkimSigningDomain();
-			this.dkimSelector = builder.getDkimSelector();
-		} else {
-			this.dkimPrivateKeyData = null;
-			this.dkimSigningDomain = null;
-			this.dkimSelector = null;
-		}
+
+		this.dkimConfig = builder.getDkimConfig();
 	}
 
 	/**
@@ -333,10 +314,8 @@ public String toString() {
 				",\n\tcontentTransferEncoding='" + contentTransferEncoding + '\'' +
 				",\n\tsubject='" + subject + '\'' +
 				",\n\trecipients=" + recipients);
-		if (!MiscUtil.valueNullOrEmpty(dkimSigningDomain)) {
-			s += ",\n\tapplyDKIMSignature=" + true +
-					",\n\t\tdkimSelector=" + dkimSelector +
-					",\n\t\tdkimSigningDomain=" + dkimSigningDomain;
+		if (!MiscUtil.valueNullOrEmpty(dkimConfig)) {
+			s += ",\n\tdkimConfig=" + dkimConfig;
 		}
 		if (TRUE.equals(useDispositionNotificationTo)) {
 			s += ",\n\tuseDispositionNotificationTo=" + true +
@@ -552,31 +531,14 @@ public Map<String, Collection<String>> getHeaders() {
 	}
 
 	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
+	 * @see EmailPopulatingBuilder#signWithDomainKey(DkimConfig)
+	 * @see EmailPopulatingBuilder#signWithDomainKey(byte[], String, String, Set)
 	 */
 	@Nullable
-	public byte[] getDkimPrivateKeyData() {
-		return dkimPrivateKeyData != null ? dkimPrivateKeyData.clone() : null;
+	public DkimConfig getDkimConfig() {
+		return dkimConfig;
 	}
 
-	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(File, String, String)
-	 */
-	@Nullable
-	public String getDkimSigningDomain() {
-		return dkimSigningDomain;
-	}
-
-	/**
-	 * @see EmailPopulatingBuilder#signWithDomainKey(InputStream, String, String)
-	 * @see EmailPopulatingBuilder#signWithDomainKey(File, String, String)
-	 */
-	@Nullable
-	public String getDkimSelector() {
-		return dkimSelector;
-	}
-
 	/**
 	 * @see EmailPopulatingBuilder#signWithSmime(Pkcs12Config)
 	 * @see EmailPopulatingBuilder#signWithSmime(InputStream, String, String, String)

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailPopulatingBuilder.java

@@ -7,11 +7,11 @@
 import jakarta.mail.util.ByteArrayDataSource;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.simplejavamail.api.email.config.DkimConfig;
 import org.simplejavamail.api.internal.clisupport.model.Cli;
 import org.simplejavamail.api.internal.clisupport.model.CliBuilderApiType;
 import org.simplejavamail.api.mailer.config.Pkcs12Config;
 
-import java.io.ByteArrayInputStream;
 import java.io.File;
 import java.io.InputStream;
 import java.net.URL;
@@ -20,11 +20,11 @@
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.regex.Pattern;
 
 import static java.util.regex.Pattern.compile;
 
-
 /**
  * Fluent interface Builder for populating {@link Email} instances. An instance of this builder can only be obtained through one of the builder
  * starters on {@link EmailStartingBuilder}.
@@ -37,8 +37,8 @@
 public interface EmailPopulatingBuilder {
 
 	/**
-	 * Regular Expression to find all {@code <img src="...">} entries in an HTML document.It needs to cater for various things, like more whitespaces including newlines on any place, HTML is not case
-	 * sensitive and there can be arbitrary text between "IMG" and "SRC" like IDs and other things.
+	 * Regular Expression to find all {@code <img src="...">} entries in an HTML document.It needs to cater for various things, like more whitespaces including newlines on any
+	 * place, HTML is not case-sensitive and there can be arbitrary text between "IMG" and "SRC" like IDs and other things.
 	 */
 	Pattern IMG_SRC_PATTERN = compile("(?<imageTagStart><[Ii][Mm][Gg]\\s*[^>]*?\\s+[Ss][Rr][Cc]\\s*=\\s*[\"'])(?<src>[^\"']+?)(?<imageSrcEnd>[\"'])");
 
@@ -1137,55 +1137,34 @@ public interface EmailPopulatingBuilder {
 	 * Delegates to {@link #withAttachment(String, DataSource)} for each attachment.
 	 */
 	EmailPopulatingBuilder withAttachments(@NotNull List<AttachmentResource> attachments);
-	
-	/**
-	 * Delegates to {@link #signWithDomainKey(InputStream, String, String)} with a {@link ByteArrayInputStream} wrapped around the prodived {@code
-	 * dkimPrivateKey} data.
-	 * <p>
-	 * <strong>Note:</strong> this only works in combination with the {@value org.simplejavamail.internal.modules.DKIMModule#NAME}.
-	 */
-	@Cli.ExcludeApi(reason = "delegated method is an identical api from CLI point of view")
-	@SuppressWarnings("unused")
-	EmailPopulatingBuilder signWithDomainKey(@NotNull byte[] dkimPrivateKey, @NotNull String signingDomain, @NotNull String dkimSelector);
-	
-	/**
-	 * Delegates to {@link #signWithDomainKey(InputStream, String, String)} with a {@link ByteArrayInputStream} wrapped around the prodived {@code
-	 * dkimPrivateKey} string converted to UTF_8 byte array.
-	 * <p>
-	 * <strong>Note:</strong> this only works in combination with the {@value org.simplejavamail.internal.modules.DKIMModule#NAME}.
-	 */
-	@Cli.ExcludeApi(reason = "delegated method is an identical api from CLI point of view")
-	@SuppressWarnings("unused")
-	EmailPopulatingBuilder signWithDomainKey(@NotNull String dkimPrivateKey, @NotNull String signingDomain, @NotNull String dkimSelector);
-	
+
 	/**
 	 * Primes this email for signing with a DKIM domain key. Actual signing is done when sending using a <code>Mailer</code>.
 	 * <p>
 	 * <strong>Note:</strong> this only works in combination with the {@value org.simplejavamail.internal.modules.DKIMModule#NAME}.
 	 *
-	 * @param dkimPrivateKeyInputStream De key content used to sign for the sending party.
-	 * @param signingDomain             The domain being authorized to send.
-	 * @param dkimSelector              Additional domain specifier.
+	 * @param dkimPrivateKey                            De key content used to sign for the sending party.
+	 * @param signingDomain                             The domain being authorized to send.
+	 * @param dkimSelector                              Additional domain specifier.
+	 * @param excludedHeadersFromDkimDefaultSigningList Allows you to exclude headers being signed, as might be the case when another mail transfer agent. For example, Amazon SES doesn't want Message-ID and Date Headers to be signed as they have internal mechanisms to handle these headers.
 	 *
 	 * @see <a href="https://postmarkapp.com/guides/dkim">more on DKIM 1</a>
 	 * @see <a href="https://github.com/markenwerk/java-utils-mail-dkim">more on DKIM 2</a>
 	 * @see <a href="http://www.gettingemaildelivered.com/dkim-explained-how-to-set-up-and-use-domainkeys-identified-mail-effectively">more on DKIM 3</a>
 	 * @see <a href="https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail">more on DKIM 4</a>
 	 * @see <a href="https://github.com/bbottema/dkim-verify">List of explanations all tags in a <em>DKIM-Signature</em> header</a>
-	 * @see #signWithDomainKey(byte[], String, String)
-	 * @see #signWithDomainKey(String, String, String)
-	 * @see #signWithDomainKey(File, String, String)
+	 * @see #signWithDomainKey(DkimConfig)
 	 */
-	EmailPopulatingBuilder signWithDomainKey(@NotNull InputStream dkimPrivateKeyInputStream, @NotNull String signingDomain, @NotNull String dkimSelector);
-	
+	@SuppressWarnings("unused")
+	EmailPopulatingBuilder signWithDomainKey(@NotNull byte[] dkimPrivateKey, @NotNull String signingDomain, @NotNull String dkimSelector, @Nullable Set<String> excludedHeadersFromDkimDefaultSigningList);
+
 	/**
-	 * As {@link #signWithDomainKey(InputStream, String, String)}, but with a File reference that is later read as {@code InputStream}.
-	 * <p>
-	 * <strong>Note:</strong> this only works in combination with the {@value org.simplejavamail.internal.modules.DKIMModule#NAME}.
+	 * @see #signWithDomainKey(byte[], String, String, Set)
 	 */
 	@Cli.ExcludeApi(reason = "delegated method is an identical api from CLI point of view")
-	EmailPopulatingBuilder signWithDomainKey(@NotNull File dkimPrivateKeyFile, @NotNull String signingDomain, @NotNull String dkimSelector);
-
+	@SuppressWarnings("unused")
+	EmailPopulatingBuilder signWithDomainKey(@NotNull DkimConfig dkimConfig);
+	
 	/**
 	 * Signs this email with an <a href="https://tools.ietf.org/html/rfc5751">S/MIME</a> signature, so the receiving client
 	 * can verify whether the email content was tampered with.
@@ -1633,26 +1612,11 @@ public interface EmailPopulatingBuilder {
 	Map<String, Collection<String>> getHeaders();
 
 	/**
-	 * @see #signWithDomainKey(InputStream, String, String)
-	 * @see #signWithDomainKey(byte[], String, String)
-	 * @see #signWithDomainKey(File, String, String)
-	 */
-	@Nullable
-	byte[] getDkimPrivateKeyData();
-	
-	/**
-	 * @see #signWithDomainKey(InputStream, String, String)
-	 * @see #signWithDomainKey(File, String, String)
-	 */
-	@Nullable
-	String getDkimSigningDomain();
-	
-	/**
-	 * @see #signWithDomainKey(InputStream, String, String)
-	 * @see #signWithDomainKey(File, String, String)
+	 * @see #signWithDomainKey(DkimConfig)
+	 * @see #signWithDomainKey(byte[], String, String, Set)
 	 */
 	@Nullable
-	String getDkimSelector();
+	DkimConfig getDkimConfig();
 
 	/**
 	 * @see #withDispositionNotificationTo()