Package com.chilkatsoft.chilkat2

Class Dkim

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Dkim
All Implemented Interfaces:
AutoCloseable
public class Dkim extends ChilkatObject
<section class="dkim-summary">

Sign and verify MIME email with DKIM signatures.

Chilkat.Dkim is the Chilkat class for applying and verifying DKIM signatures on MIME email data. It supports DKIM signing with rsa-sha256 or rsa-sha1, configurable canonicalization, selectable signed headers, signature counting, DNS public-key lookup, public-key caching, public-key prefetching, and detailed verification reporting through VerifyInfo.

DKIM signing

Add DKIM signatures to MIME messages using a private key, selector, signing domain, canonicalization settings, and selected headers.

Signed header selection

Choose which message headers are protected by the signature and control their order in the generated h= tag.

Signature verification

Verify one or more signatures in a MIME message and determine whether the signed content, headers, and public key match.

Canonicalization control

Configure body and header canonicalization so signing and verification match the requirements of the sending domain and receiving systems.

DNS public keys

Retrieve DKIM public keys from DNS, prefetch keys when useful, and cache public keys to reduce repeated DNS lookups.

Verification diagnostics

Use VerifyInfo and related status information to understand which signatures were found, which were checked, and why verification succeeded or failed.

Common pattern: To sign, provide the MIME message, signing domain, selector, private key, canonicalization choices, and the headers to include in the signature. To verify, pass the received MIME message to Dkim, allow the class to locate the signature and public key, and inspect VerifyInfo for detailed results.

For an extended overview, see Dkim Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Dkim

      public Dkim()
      Creates a new Dkim object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set to true to request cancellation of a currently running operation. A synchronous operation can be cancelled from another thread by setting this property on the same object. Methods that complete quickly or do not periodically check for cancellation may finish before the request is observed. Cancellation behavior: Treat this as a cancellation request rather than a guarantee of immediate termination. After the method returns, use the method's normal return value and diagnostic properties to determine the outcome.
      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getDkimAlg

      public String getDkimAlg()
      Specifies the signing algorithm written to the a= tag of a newly created DKIM-Signature header. The default is rsa-sha256.

      Value Behavior

      rsa-sha256 RSA signing with a SHA-256 digest. This is the recommended value.

      rsa-sha1 Legacy RSA signing with a SHA-1 digest. Use only when an older system specifically requires it.

      The value is trimmed and compared case-insensitively. The recognized values are rsa-sha256 and rsa-sha1. An empty or unrecognized value is normalized to rsa-sha256 rather than rejected.

      Returns:
      the value of the DkimAlg property

    • setDkimAlg

      public void setDkimAlg​(String value)
      Sets the DkimAlg property; see getDkimAlg().
      Parameters:
      value - the new value (not null)

    • getDkimBodyLengthCount

      public int getDkimBodyLengthCount()
      Controls the maximum number of bytes from the canonicalized message body used when computing the DKIM body hash. The default is 0.

      Value Behavior

      0 Hashes the complete canonicalized body and omits the DKIM l= tag.

      Positive and less than the canonicalized body length Hashes the specified number of bytes and emits l= with that value.

      Positive and greater than the canonicalized body length Hashes the complete canonicalized body and emits l= containing the actual canonicalized body length.

      Negative -1 hashes the complete canonicalized body and emits l= containing the actual canonicalized body length.

      When a generated signature contains l=, verification hashes only the indicated prefix of the canonicalized body. Content appended after that signed prefix does not invalidate the signature.

      Security note: Partial-body signatures allow unsigned content to be appended after the signed portion. Signing the complete body by using 0 is normally preferred.

      Returns:
      the value of the DkimBodyLengthCount property

    • setDkimBodyLengthCount

      public void setDkimBodyLengthCount​(int value)
      Sets the DkimBodyLengthCount property; see getDkimBodyLengthCount().
      Parameters:
      value - the new value

    • getDkimCanon

      public String getDkimCanon()
      Specifies one DKIM canonicalization algorithm to use for both the signed header fields and the message body. The default is relaxed.

      Value Generated c= value Behavior

      simple simple/simple Preserves formatting closely. Small changes in whitespace or header folding can invalidate the signature.

      relaxed relaxed/relaxed Normalizes defined whitespace and header-name differences.

      The value is trimmed and compared case-insensitively. This property does not accept a header/body pair such as relaxed/simple or simple/relaxed. Pair values, an empty string, and other unrecognized values are normalized to relaxed rather than rejected.

      Canonicalization background: DKIM signs a canonicalized representation of the message. The signer and verifier must apply the same header and body canonicalization rules.

      Returns:
      the value of the DkimCanon property

    • setDkimCanon

      public void setDkimCanon​(String value)
      Sets the DkimCanon property; see getDkimCanon().
      Parameters:
      value - the new value (not null)

    • getDkimDomain

      public String getDkimDomain()
      Specifies the signing domain written verbatim to the d= tag of the generated DKIM-Signature header. The corresponding public key is normally published beneath the DNS name formed from getDkimSelector() and this domain.

      Set this property to a nonempty, syntactically valid domain before calling dkimSign(BinData). If this property is empty, DkimSign returns false without modifying the MIME data. A nonempty value is not otherwise validated or normalized during signing; uppercase letters, surrounding whitespace, a trailing dot, and Unicode characters are emitted as supplied.

      Caller responsibility: Supply the domain in the exact form required in the signature. For an internationalized domain, use its ASCII/Punycode form. DkimSign does not check DNS and does not confirm that the configured private key matches the public key published for this domain. DKIM and DMARC: DKIM verification does not require d= to equal the visible From domain. DMARC separately evaluates alignment between the authenticated DKIM domain and the message's From domain.

      Returns:
      the value of the DkimDomain property

    • setDkimDomain

      public void setDkimDomain​(String value)
      Sets the DkimDomain property; see getDkimDomain().
      Parameters:
      value - the new value (not null)

    • getDkimHeaders

      public String getDkimHeaders()
      A colon-separated list of header field names to include in the DKIM signature. The list is written to the signature's h= tag in the same order. The default is: 
      mime-version:date:message-id:subject:from:to:content-type

      Header-name matching is case-insensitive. For each occurrence of a name in this list, Chilkat selects the next matching header field from the bottom of the message header block upward, as required by DKIM. For example, if the message contains two Subject fields, listing subject once signs the bottommost field, while listing it twice signs both fields.

      If a listed occurrence has no corresponding field in the message, the absent field is still included in the signing calculation. Repeating a name more times than it occurs can therefore implement DKIM oversigning and prevent a matching field from being inserted later without invalidating the signature.

      • Use colon-separated field names without surrounding spaces.
      • Include from; DKIM requires the From field to be signed, but dkimSign(BinData) does not enforce this requirement or add it automatically.
      • An empty list and names of missing fields are accepted rather than rejected.
      • Avoid transport-added or frequently modified fields such as Received and Return-Path.

      Repeated names: Repeated existing headers are signed successively from bottom to top. Repeated absent occurrences are useful for oversigning.

      Returns:
      the value of the DkimHeaders property

    • setDkimHeaders

      public void setDkimHeaders​(String value)
      Sets the DkimHeaders property; see getDkimHeaders().
      Parameters:
      value - the new value (not null)

    • getDkimSelector

      public String getDkimSelector()
      Specifies the selector written verbatim to the s= tag of a generated DKIM signature. The selector and getDkimDomain() form the DNS name used to locate the public key: 
      selector._domainkey.signing-domain

      For example, selector brisbane and domain chilkatsoft.com produce brisbane._domainkey.chilkatsoft.com.

      Supply only the selector. Do not include ._domainkey. or the signing domain. If this property is empty, dkimSign(BinData) returns false without modifying the MIME data. A nonempty value is not otherwise validated or normalized during signing; for example, a complete DNS name is emitted as supplied rather than reduced to a selector.

      Caller responsibility: Use a nonempty selector consisting of valid DNS selector labels. The private key configured by setDkimPrivateKey(PrivateKey) must match the public key published for this selector and domain.

      Returns:
      the value of the DkimSelector property

    • setDkimSelector

      public void setDkimSelector​(String value)
      Sets the DkimSelector property; see getDkimSelector().
      Parameters:
      value - the new value (not null)

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck callbacks during methods that support periodic cancellation checks. Set to 0 to disable these callbacks. The default is 0.

      prefetchPublicKey(String, String) invokes AbortCheck while performing its DNS lookup. Setting this property to 1 and requesting cancellation from the first callback causes PrefetchPublicKey to return false.

      Responsiveness and overhead: A smaller interval can make cancellation more responsive, but it also increases callback overhead. Methods that finish quickly may complete before any callback occurs.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getVerifyInfo

      public String getVerifyInfo()
      Contains JSON describing the most recent call to dkimVerify(int, BinData). The property is initially an empty string and is replaced or cleared by each verification attempt.

      Member Meaning

      domain The signature's d= value.

      selector The signature's s= value.

      publicKey The Base64 public-key value obtained from DNS. This member is present when verification performs an automatic DNS lookup and may be absent when a preloaded or prefetched key is used.

      canonicalization The header/body canonicalization pair from c=.

      algorithm The signature algorithm from a=.

      signedHeaders The signed-header list from h=.

      fromSigned Indicates whether the required From field name is included in the signed-header list.

      expectedBodyHash The Base64 body hash obtained from the signature's bh= tag.

      computedBodyHash The Base64 body hash computed from the received message, applying the signature's canonicalization and optional l= body-length limit.

      bodyHashVerified The string "yes" when the computed body hash matches bh=, or "no" when it does not.

      verified The string "yes" for a valid signature or "no" for a completed verification that failed. 

      {
   "domain": "chilkatsoft.com",
   "selector": "brisbane",
   "canonicalization": "relaxed/relaxed",
   "algorithm": "rsa-sha256",
   "signedHeaders": "from:to:subject:date:message-id",
   "fromSigned": "yes",
   "expectedBodyHash": "...",
   "computedBodyHash": "...",
   "bodyHashVerified": "yes",
   "verified": "yes"
 }

      Not every member is present in every result. For malformed signatures, unsupported algorithms, missing signatures, DNS failures, or an out-of-range index, the value may be an empty string, {}, or a partial object without verified. Therefore, first check the return value of DkimVerify, and then treat individual JSON members as optional.

      Authentication scope: A valid DKIM signature shows that the verified signed content was produced by an entity possessing the private key for the authenticated domain. It does not by itself prove the identity of the human sender or establish DMARC alignment.

      Returns:
      the value of the VerifyInfo property (read-only)

    • dkimSign

      public void dkimSign​(BinData mimeData)
      Creates a DKIM-Signature header and prepends it to the complete MIME message stored in mimeData. The BinData is modified in place.

      Before calling this method:

      On success, the generated header contains v=1, a=, c=, q=dns/txt, d=, s=, h=, bh=, and b=. When getDkimBodyLengthCount() is nonzero, the header also contains l=. The generated header does not include t=, x=, or i=. Signing the same bytes twice with the same settings and key produced identical output.

      An empty body, a body without a final newline, and body data containing NUL or other binary bytes are accepted. An empty getDkimDomain(), an empty getDkimSelector(), missing or invalid private-key state, or malformed MIME causes the method to return false without changing mimeData.

      Existing signatures: A new signature is prepended and existing DKIM-Signature fields are preserved. Signature indexes therefore follow top-to-bottom order: the newly added signature is index 0, and older signatures shift to higher indexes. Each signature can be verified independently. Sign the final representation: Send the signed bytes directly. Parsing and regenerating the message, changing line endings, refolding signed headers, changing transfer encodings, or editing the signed body can invalidate the signature.

      Parameters:
      mimeData - the mimeData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • dkimVerify

      public void dkimVerify​(int sigIndex, BinData mimeData)
      Verifies the DKIM-Signature header at zero-based sigIndex in the complete MIME message stored in mimeData. Signatures are indexed in top-to-bottom header order. Use numDkimSigs(BinData) to obtain the count.

      Chilkat first looks for a public key cached under the exact selector/domain strings. If no exact match exists, it synchronously retrieves the TXT record at selector._domainkey.domain. The method does not modify mimeData.

      Return value Meaning

      true The selected signature was successfully verified, including its body hash and signed headers.

      false The signature was invalid, or verification could not be completed because of an invalid index, malformed signature, unsupported algorithm, missing key, DNS failure, or another operational error.

      Verification compares the signature's bh= value with the hash computed from the canonicalized body. When the signature contains l=, only the indicated number of canonicalized body bytes are included, so content appended after the signed prefix does not cause a body-hash failure.

      After the call, inspect getVerifyInfo(). A completed verification failure normally contains "verified":"no". A body-hash mismatch also contains "bodyHashVerified":"no" with the expected and computed hashes. Operational and parsing failures may leave an empty string, {}, or a partial JSON object; use LastErrorText for the detailed reason.

      Multiple signatures: Verify each signature independently. One valid signature does not imply that every signature on the message is valid.

      Parameters:
      sigIndex - the sigIndex argument
      mimeData - the mimeData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPublicKey

      public void loadPublicKey​(String selector, String domain, String publicKey)
      Loads and caches an RSA public key in this Dkim object for the exact selector and domain strings. A later dkimVerify(int, BinData) uses the cached key when the signature contains the same selector and domain; otherwise verification falls back to DNS.

      publicKey contains a textual key representation. Supported formats include:

      • PEM X.509 SubjectPublicKeyInfo (-----BEGIN PUBLIC KEY-----)
      • PEM PKCS#1 RSA public key (-----BEGIN RSA PUBLIC KEY-----)
      • XML RSA key data
      • RSA JWK JSON

      The selector/domain cache key is case-sensitive. Loading a key for uppercase values does not satisfy a lowercase signature. A successful later load for the same pair replaces the earlier key. If a later load fails because the supplied key text is invalid, the previously cached key remains available.

      Typical use: Preload a trusted public key for testing before DNS publication or for a controlled verification environment. The key data is copied into the cache; the input string does not need to remain available after this method returns.

      Parameters:
      selector - the selector argument (not null)
      domain - the domain argument (not null)
      publicKey - the publicKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPublicKeyFile

      public void loadPublicKeyFile​(String selector, String domain, String publicKeyFilepath)
      Loads an RSA public key from the local file at publicKeyFilepath and caches it in this Dkim object for the exact selector and domain strings. The file is read during this call.

      Supported formats include PEM X.509 SubjectPublicKeyInfo, PEM PKCS#1 RSA public key, binary DER PKCS#1 RSA public key, XML RSA key data, and RSA JWK JSON. The selector/domain cache key is case-sensitive.

      A later successful load for the same selector/domain pair replaces the earlier cached key. If no exact cached key is present when dkimVerify(int, BinData) runs, Chilkat performs its normal DNS lookup.

      Path and trust: publicKeyFilepath is a path in the local filesystem. Load only keys from a trusted source because the cached key determines which signatures are accepted for that selector and domain.

      Parameters:
      selector - the selector argument (not null)
      domain - the domain argument (not null)
      publicKeyFilepath - the publicKeyFilepath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • numDkimSigs

      public int numDkimSigs​(BinData mimeData)
      Returns the number of header fields named DKIM-Signature in mimeData. Header-name matching is case-insensitive. The method counts matching fields without validating the signature syntax; for example, a malformed DKIM-Signature: nonsense field is still counted.

      The indexes used by dkimVerify(int, BinData) are zero-based and follow top-to-bottom header order. The method returns 0 when no matching header is found, including for an empty message. It does not modify mimeData.

      Counting versus validation: This method is a header count, not a MIME or DKIM validation step. A positive result does not mean that any counted signature is well formed or verifiable.

      Parameters:
      mimeData - the mimeData argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • prefetchPublicKey

      public void prefetchPublicKey​(String selector, String domain)
      Retrieves the DKIM public key from DNS and caches it in this Dkim object for the exact selector and domain strings. The TXT lookup is made for: 
      selector._domainkey.domain

      The method returns true when the DNS lookup and public-key loading succeed. Repeated calls for a cached pair can complete without another observable lookup. A successful prefetch replaces an existing manually loaded key for the same selector/domain pair.

      dkimVerify(int, BinData) also performs this DNS lookup automatically when no exact cached key is available. Prefetching is useful when several messages will be verified for the same selector and domain.

      Cancellation: This method supports AbortCheck callbacks according to getHeartbeatMs(). When the callback requests cancellation, the method returns false and the DNS lookup is aborted. Key rotation: The selector identifies a particular published key. When a sender begins using a new selector, prefetch the new selector separately.

      Parameters:
      selector - the selector argument (not null)
      domain - the domain argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setDkimPrivateKey

      public void setDkimPrivateKey​(PrivateKey privateKey)
      Copies the RSA key from privateKey into this object for subsequent calls to dkimSign(BinData). The source PrivateKey object may be destroyed after this method returns successfully, and the configured key can be reused for multiple signatures.

      A later successful call replaces the previously configured signing key. A failed call with an empty or unrecognized key clears the usable signing-key state; a subsequent DkimSign fails until a valid key is set again.

      Key matching: The private key must correspond to the public key published at selector._domainkey.domain, using getDkimSelector() and getDkimDomain(). This method does not check DNS or confirm the match.

      Parameters:
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener