Package com.chilkatsoft.chilkat2

Class Mime

java.lang.Object

com.chilkatsoft.chilkat2.ChilkatObject

com.chilkatsoft.chilkat2.Mime

All Implemented Interfaces:

AutoCloseable

public class Mime
extends ChilkatObject

<section class="mime-summary">

Build, parse, modify, serialize, secure, and inspect MIME and S/MIME data.

Mime provides low-level MIME and S/MIME handling for applications that need direct control over MIME structure, headers, body content, encodings, multipart relationships, attachments, and PKCS7/CMS security layers. It can load, create, inspect, modify, serialize, and save MIME messages; build multipart structures; manage headers and content-transfer encodings; extract attachments; convert MIME to and from XML; and sign, verify, encrypt, decrypt, or unwrap S/MIME content.

Create and load MIME

Build MIME content programmatically or load existing MIME from strings, files, byte data, or other application sources.

Headers and body content

Read, add, replace, or remove MIME headers, set body content, and control content types, charsets, and transfer encodings.

Multipart structures

Create and inspect multipart MIME trees such as mixed, alternative, related, signed, encrypted, and nested MIME structures.

Attachments and parts

Add, locate, extract, remove, or inspect MIME parts and attachments, including filenames and encoded body data.

S/MIME security

Sign, verify, encrypt, decrypt, unwrap, and inspect PKCS7/CMS S/MIME layers using certificates and private keys.

Serialization and XML

Emit MIME text, save MIME to files, or convert MIME to and from XML for structured inspection, transformation, or storage.

Common pattern: Use Mime when an application needs low-level control over MIME parts, headers, encodings, multipart layout, or S/MIME security. For ordinary email composition and message-level operations, use Email; use Mime when you need to work closer to the raw MIME structure.

Initial state: A new Mime object has no headers or child parts. Its string serialization consists only of the blank header/body separator (CRLF CRLF) until content is added.

MIME parsing is semantic, not byte-preserving. Loading and reserializing can unfold headers, normalize parameter quoting and transfer encodings, use CRLF for generated headers and multipart framing, and discard multipart preamble or epilogue text. Use byte-oriented methods such as loadMimeBd(BinData) and getMimeBd(BinData) when arbitrary 8-bit bytes or embedded NUL bytes must be preserved.

For an extended overview, see Mime Class Overview.

</section>

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 Summary

Constructors

Constructor	Description
Mime()	Creates a new Mime object.

Method Summary

Modifier and Type	Method	Description
void	addContentLength()	Computes the byte length of the current entity's serialized MIME body and adds or updates its Content-Length header.
void	addDecryptCert(Cert cert)	Adds cert to the internal collection of certificates available for S/MIME decryption.
void	addDetachedSignature(Cert cert)	Creates an S/MIME detached signature using cert.
void	addDetachedSignature2(Cert cert, boolean transferHeaderFields)	Creates the same detached multipart/signed structure as addDetachedSignature(Cert).
void	addDetachedSignaturePk(Cert cert, PrivateKey privateKey)	Creates a detached S/MIME signature using cert as the signer certificate and privateKey as its associated private key.
void	addDetachedSignaturePk2(Cert cert, PrivateKey privateKey, boolean transferHeaderFields)	Creates a detached S/MIME signature using the certificate in cert and the corresponding private key in privateKey.
void	addEncryptCert(Cert cert)	Adds cert to the internal recipient-certificate list used by encryptN().
void	addHeaderField(String name, String value)	Appends a new header field named by name with the value in value.
void	addPfxSourceBd(BinData bd, String password)	Adds the PKCS #12/PFX bytes in bd to the internal collection of credential sources used by later S/MIME decryption operations.
void	addPfxSourceFile(String pfxFilePath, String password)	Adds the PFX/P12 file at the local filesystem path in pfxFilePath to the internal collection of credential sources used by later S/MIME decryption operations.
void	appendPart(Mime mime)	Appends a copy of mime as the last direct child.
void	appendPartFromFile(String filename)	Reads the local file at filename, creates an attachment part, and appends it.
String	asnBodyToXml()	Parses the current part's decoded body as ASN.1 DER and returns an XML representation of the ASN.1 structure.
void	clearEncryptCerts()	Clears the internal recipient-certificate list populated by addEncryptCert(Cert).
boolean	containsEncryptedParts()	Returns true if the currently visible MIME tree contains a CMS/PKCS #7 encrypted entity.
boolean	containsSignedParts()	Returns true if the currently visible MIME tree contains a complete detached or opaque CMS/PKCS #7 signed entity.
void	convert8Bit()	Recursively converts every part whose Content-Transfer-Encoding is 8bit or binary to base64.
void	convertToMultipartAlt()	Wraps the current entity in a new outer multipart/alternative entity.
void	convertToMultipartMixed()	Wraps the current entity in a new outer multipart/mixed entity.
void	convertToSigned(Cert cert)	Creates an opaque (attached) S/MIME signature using cert.
void	convertToSignedPk(Cert cert, PrivateKey privateKey)	Creates an opaque (attached) S/MIME signature using cert as the signer certificate and privateKey as its associated private key.
void	decrypt()	Decrypts the current CMS/PKCS #7 encrypted MIME entity and replaces it with the recovered MIME content.
void	decrypt2(Cert cert, PrivateKey privateKey)	Decrypts the current CMS/PKCS #7 encrypted MIME entity using the certificate in cert and its associated private key in privateKey.
void	decryptUsingCert(Cert cert)	Decrypts the current CMS/PKCS #7 encrypted MIME entity using cert.
void	decryptUsingPfxFile(String pfxFilePath, String pfxPassword)	Decrypts the current CMS/PKCS #7 encrypted MIME entity using certificates and private keys from the PFX/P12 file at the local filesystem path in pfxFilePath.
void	encrypt(Cert cert)	Encrypts the current MIME entity for the recipient certificate in cert and replaces it with CMS/PKCS #7 encrypted S/MIME.
void	encryptN()	Encrypts the current MIME entity for every certificate previously added with addEncryptCert(Cert).
void	getBodyBd(BinData binDat)	Replaces the contents of binDat with the decoded body bytes of the current part.
String	getBodyDecoded()	Returns the decoded body as text.
String	getBodyEncoded()	Returns the current part's transfer-encoded body text without decoding Base64 or quoted-printable.
String	getBoundary()	Gets or sets the raw boundary token used by a multipart MIME entity.
String	getCharset()	Gets or sets the charset parameter of the Content-Type header field.
String	getCmsOptions()	Gets or sets a JSON string containing advanced CMS/PKCS #7 signing and validation options.
String	getContentType()	Gets or sets the MIME media type of the current part, excluding all parameters.
String	getCurrentDateTime()	Returns the current local date and time formatted as an Internet message date, including the numeric UTC offset.
void	getDecryptCertInfo(JsonObject certInfo)	Examines the current encrypted S/MIME entity and writes recipient-certificate identifiers to the JsonObject in certInfo.
String	getDisposition()	Gets or sets the disposition value from the Content-Disposition header field, excluding parameters such as filename.
String	getEncoding()	Gets or sets the value of the Content-Transfer-Encoding header field for the current part.
String	getEntireBody()	Returns the complete serialized body of the current MIME entity.
String	getEntireHead()	Returns the complete serialized header section of the current MIME entity.
String	getFilename()	Gets or sets the filename parameter of the Content-Disposition header field.
String	getHeaderField(String fieldName)	Returns the value of the first header field whose name matches fieldName case-insensitively.
String	getHeaderFieldAttribute(String name, String attrName)	Returns an attribute value parsed from the first header field named by name.
String	getHeaderFieldName(int index)	Returns the name of the header-field occurrence at zero-based index.
String	getHeaderFieldValue(int index)	Returns the unfolded value of the header-field occurrence at zero-based index.
void	getLastJsonData(JsonObject json)	Copies structured details from the most recent operation into json when such details are available.
String	getMicalg()	Gets or sets the micalg parameter of a multipart/signed Content-Type header field.
String	getMime()	Serializes and returns the complete MIME entity, including headers, body, multipart boundaries, and all descendants.
void	getMimeBd(BinData bindat)	Serializes the complete MIME entity and appends its bytes to bindat.
void	getMimeSb(StringBuilder sb)	Serializes the complete MIME entity and appends it to sb.
String	getName()	Gets or sets the name parameter of the Content-Type header field.
int	getNumDecryptCerts()	Returns the number of recipient or decryption certificates currently recorded by the most recent S/MIME encryption, decryption, or security-unwrapping operation.
int	getNumHeaderFields()	Returns the number of header-field occurrences in the current part.
int	getNumParts()	Returns the number of direct child parts.
int	getNumSignerCerts()	Returns the number of signer certificates currently recorded by the most recent S/MIME signing, signature-verification, or security-unwrapping operation.
String	getOaepHash()	Gets or sets the hash algorithm used by RSAES-OAEP when encrypting the CMS content-encryption key.
String	getOaepMgfHash()	Gets or sets the hash algorithm used by the MGF1 mask generation function within RSAES-OAEP.
boolean	getOaepPadding()	Selects the RSA key-transport padding used when creating encrypted MIME.
String	getPkcs7CryptAlg()	Gets or sets the symmetric content-encryption algorithm used when creating CMS/PKCS #7 encrypted MIME.
int	getPkcs7KeyLength()	Gets or sets the content-encryption key length, in bits, used when creating CMS/PKCS #7 encrypted MIME.
String	getProtocol()	Gets or sets the protocol parameter of the Content-Type header field.
String	getSignatureSigningTimeStr(int index)	Returns the CMS signingTime signed attribute for the signer at zero-based index, formatted as an RFC 822-style date string in GMT.
String	getSigningAlg()	Gets or sets the RSA signature scheme used when creating CMS/PKCS #7 signed MIME.
String	getSigningHashAlg()	Gets or sets the message-digest algorithm used when creating CMS/PKCS #7 signatures.
String	getStructure(String fmt)	Returns a concise MIME-tree summary.
String	getUncommonOptions()	Gets or sets a semicolon-delimited or implementation-specific option string used for uncommon compatibility requirements.
boolean	getUnwrapExtras()	Controls whether unwrapSecurity() adds informative header fields describing the security layers removed.
boolean	getUseMmDescription()	Controls whether Chilkat uses the conventional multipart preamble text This is a multi-part message in MIME format. when serializing a multipart entity.
boolean	getUseXPkcs7()	Controls whether newly created S/MIME media types use the historical x-pkcs7 names.
String	getXml()	Converts the MIME tree to Chilkat's XML representation and returns it as a string.
boolean	hasSignatureSigningTime(int index)	Returns true if the signer at zero-based index has a CMS signingTime signed attribute.
boolean	isApplicationData()	Returns true when getContentType() begins with application/.
boolean	isAttachment()	Returns true when the current part's disposition value is attachment, matched case-insensitively.
boolean	isAudio()	Returns true when getContentType() begins with audio/.
boolean	isEncrypted()	Returns true when the current MIME entity is a CMS/PKCS #7 encrypted S/MIME wrapper.
boolean	isHtml()	Returns true when getContentType() is text/html.
boolean	isImage()	Returns true when getContentType() begins with image/, including values such as image/svg+xml.
boolean	isMultipart()	Returns true when getContentType() begins with multipart/.
boolean	isMultipartAlternative()	Returns true when getContentType() is multipart/alternative.
boolean	isMultipartMixed()	Returns true when getContentType() is multipart/mixed.
boolean	isMultipartRelated()	Returns true when getContentType() is multipart/related.
boolean	isPlainText()	Returns true when getContentType() is text/plain.
boolean	isSigned()	Returns true when the current MIME entity is a complete CMS/PKCS #7 signed S/MIME wrapper, including detached multipart/signed and opaque signed-data forms.
boolean	isText()	Returns true when getContentType() begins with text/.
boolean	isVideo()	Returns true when getContentType() begins with video/.
boolean	isXml()	Returns true only for text/xml or application/xml.
void	lastDecryptCert(int index, Cert cert)	Loads into cert the decryption certificate at zero-based index from the most recent successful decryption or security-unwrapping operation.
void	lastSignerCert(int index, Cert cert)	Loads into cert the signer certificate at zero-based index from the most recent successful signature-verification or security-unwrapping operation.
void	loadMime(String mimeMsg)	Parses the complete MIME text in mimeMsg and replaces the current object's headers, body, and multipart tree.
void	loadMimeBd(BinData bindat)	Parses complete MIME bytes from bindat and replaces the current MIME on success.
void	loadMimeFile(String fileName)	Reads and parses the complete MIME entity from the local file at fileName.
void	loadMimeSb(StringBuilder sb)	Parses complete MIME text from sb and replaces the current MIME on success.
void	loadXml(String xml)	Reconstructs a MIME tree from Chilkat's MIME XML in xml.
void	loadXmlFile(String fileName)	Reads Chilkat MIME XML from the local file at fileName and reconstructs the MIME tree.
void	newMessageRfc822(Mime mimeObject)	Clears the current object and initializes it as message/rfc822.
void	newMultipartAlternative()	Initializes an empty multipart/alternative entity.
void	newMultipartMixed()	Initializes an empty multipart/mixed entity.
void	newMultipartRelated()	Initializes an empty multipart/related entity.
void	partAt(int index, Mime subPart)	Provides live access to the direct child at zero-based index through subPart.
void	partsToFiles(String path, StringTable st)	Recursively traverses the MIME tree and saves each part having a nonempty filename parameter to the existing directory in path.
void	removeHeaderField(String fieldName, boolean bAllOccurrences)	Removes fields whose name matches fieldName case-insensitively.
void	removePart(int index)	Removes the direct child at zero-based index.
void	saveBody(String filename)	Writes the decoded body bytes of the current part to the local path in filename.
void	saveMime(String filename)	Serializes the complete MIME entity and writes it to the local path in filename, including headers, body, multipart boundaries, and all descendants.
void	saveXml(String filename)	Writes Chilkat's MIME XML representation to the local path in filename.
void	setBody(String str)	Sets the current part's body from str while preserving existing content headers such as Content-Type, charset, and Content-Transfer-Encoding.
void	setBodyBd(BinData bd)	Sets the decoded body bytes from bd, changes Content-Transfer-Encoding to base64, and preserves the bytes exactly.
void	setBodyFromEncoded(String encoding, String str)	Sets the body from transfer-encoded text.
void	setBodyFromFile(String fileName)	Reads the local file at fileName and replaces the current part's body and content headers according to the filename extension.
void	setBodyFromHtml(String str)	Sets str as HTML and changes the media type to text/html.
void	setBodyFromPlainText(String str)	Sets str as plain text.
void	setBodyFromXml(String str)	Sets str as XML, changes the media type to text/xml, and selects a transfer encoding appropriate for the text.
void	setBoundary(String value)	Sets the Boundary property; see getBoundary().
void	setCharset(String value)	Sets the Charset property; see getCharset().
void	setCmsOptions(String value)	Sets the CmsOptions property; see getCmsOptions().
void	setContentType(String value)	Sets the ContentType property; see getContentType().
void	setDisposition(String value)	Sets the Disposition property; see getDisposition().
void	setEncoding(String value)	Sets the Encoding property; see getEncoding().
void	setFilename(String value)	Sets the Filename property; see getFilename().
void	setHeaderField(String name, String value)	Sets one header field named by name.
void	setMicalg(String value)	Sets the Micalg property; see getMicalg().
void	setName(String value)	Sets the Name property; see getName().
void	setOaepHash(String value)	Sets the OaepHash property; see getOaepHash().
void	setOaepMgfHash(String value)	Sets the OaepMgfHash property; see getOaepMgfHash().
void	setOaepPadding(boolean value)	Sets the OaepPadding property; see getOaepPadding().
void	setPkcs7CryptAlg(String value)	Sets the Pkcs7CryptAlg property; see getPkcs7CryptAlg().
void	setPkcs7KeyLength(int value)	Sets the Pkcs7KeyLength property; see getPkcs7KeyLength().
void	setProtocol(String value)	Sets the Protocol property; see getProtocol().
void	setSigningAlg(String value)	Sets the SigningAlg property; see getSigningAlg().
void	setSigningHashAlg(String value)	Sets the SigningHashAlg property; see getSigningHashAlg().
void	setUncommonOptions(String value)	Sets the UncommonOptions property; see getUncommonOptions().
void	setUnwrapExtras(boolean value)	Sets the UnwrapExtras property; see getUnwrapExtras().
void	setUseMmDescription(boolean value)	Sets the UseMmDescription property; see getUseMmDescription().
void	setUseXPkcs7(boolean value)	Sets the UseXPkcs7 property; see getUseXPkcs7().
void	setVerifyCert(Cert cert)	Supplies cert as a signer-certificate fallback for subsequent signature verification.
void	unwrapSecurity()	Removes supported S/MIME security layers and restores the underlying MIME content.
void	urlEncodeBody(String charset)	Replaces the current body with an application/x-www-form-urlencoded-style representation using the character set named by charset.
void	useCertVault(XmlCertVault vault)	Sets vault as the certificate vault used to locate certificates and private keys for S/MIME encryption, decryption, signing, and verification.
void	verify()	Verifies the current CMS/PKCS #7 signed MIME entity and removes the signature wrapper.

Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Mime

public Mime()

Creates a new Mime object.

Method Details

getBoundary

public String getBoundary()

Gets or sets the raw boundary token used by a multipart MIME entity. Do not include surrounding quotation marks.

Content-Type: multipart/mixed; boundary="example-boundary"

For this example, Boundary is example-boundary. Chilkat automatically quotes the parameter when the token contains characters such as spaces or semicolons. Normally automatic. Methods such as newMultipartMixed(), newMultipartAlternative(), and newMultipartRelated() generate a nonempty boundary. Caller-supplied boundaries are not validated. Chilkat does not detect collisions with body text. An empty value is permitted but produces invalid multipart delimiters, and supplying quotation marks as part of the property value causes those quotation marks to become part of the boundary. The property can also be set on a nonmultipart entity, where it is simply added as a Content-Type parameter.

Returns:

the value of the Boundary property

setBoundary

public void setBoundary(String value)

Sets the Boundary property; see getBoundary().

Parameters:

value - the new value (not null)

getCharset

public String getCharset()

Gets or sets the charset parameter of the Content-Type header field.

Content-Type: text/plain; charset=utf-8

Changing this property preserves the media type and other parameters. Setting it when no Content-Type exists creates a Content-Type field, although the media type remains empty until getContentType() is set. Charset versus transfer encoding. The charset identifies how text characters are represented as bytes. getEncoding() controls the MIME transport representation of those bytes. Empty-string behavior. Setting Charset to an empty string does not remove the parameter. It selects the platform default ANSI charset; on Windows this is typically windows-1252.

Returns:

the value of the Charset property

setCharset

public void setCharset(String value)

Sets the Charset property; see getCharset().

Parameters:

value - the new value (not null)

getCmsOptions

public String getCmsOptions()

Gets or sets a JSON string containing advanced CMS/PKCS #7 signing and validation options. The default is an empty string, which selects normal behavior. A valid empty JSON object may also be supplied as {}.

Unknown JSON members are retained but ignored. Malformed JSON is normalized to {}. This property is intended for specialized interoperability requirements; applications should leave it empty unless a documented option is specifically needed.

Returns:

the value of the CmsOptions property

setCmsOptions

public void setCmsOptions(String value)

Sets the CmsOptions property; see getCmsOptions().

Parameters:

value - the new value (not null)

getContentType

public String getContentType()

Gets or sets the MIME media type of the current part, excluding all parameters. Supply a value such as text/plain, text/html, application/pdf, or multipart/mixed; do not include charset, boundary, or other parameters in this property.

Changing the media type preserves the existing charset and unrecognized parameters, but may remove parameters that are specific to the previous media type, such as format=flowed. Setting an empty string leaves an empty media type and can therefore produce an invalid-looking header if other parameters remain.

Classification methods use this value. Methods such as isText(), isImage(), and isMultipart() classify the media type stored here. Parameters must be set through their dedicated properties or header attributes, not appended to ContentType.

Returns:

the value of the ContentType property

setContentType

public void setContentType(String value)

Sets the ContentType property; see getContentType().

Parameters:

value - the new value (not null)

getCurrentDateTime

public String getCurrentDateTime()

Returns the current local date and time formatted as an Internet message date, including the numeric UTC offset. For example:

Fri, 21 Nov 1997 09:55:06 -0600

Returns:

the value of the CurrentDateTime property (read-only)

getDisposition

public String getDisposition()

Gets or sets the disposition value from the Content-Disposition header field, excluding parameters such as filename.

Content-Disposition: attachment; filename="report.pdf"

Changing this property preserves an existing filename parameter. Typical values are attachment and inline.

Returns:

the value of the Disposition property

setDisposition

public void setDisposition(String value)

Sets the Disposition property; see getDisposition().

Parameters:

value - the new value (not null)

getEncoding

public String getEncoding()

Gets or sets the value of the Content-Transfer-Encoding header field for the current part. Common values include base64, quoted-printable, 7bit, 8bit, and binary. Transfer encoding is not compression. It determines how the body bytes are represented in serialized MIME. getBodyEncoded() returns the transfer-encoded form, while getBodyBd(BinData), GetBodyBinary, and saveBody(String) return or save decoded bytes.

Returns:

the value of the Encoding property

setEncoding

public void setEncoding(String value)

Sets the Encoding property; see getEncoding().

Parameters:

value - the new value (not null)

getFilename

public String getFilename()

Gets or sets the filename parameter of the Content-Disposition header field. The value is a receiver-facing filename, not a local filesystem path.

Changing this property preserves the disposition value but removes other Content-Disposition parameters such as size. Setting an empty string removes the filename parameter.

International filenames. When setting a non-ASCII filename, Chilkat emits an RFC 2047 encoded-word in filename=. When reading a header containing both filename= and filename*=, this property returns filename=. Use getHeaderFieldAttribute(String, String) to retrieve the raw filename* value.

Returns:

the value of the Filename property

setFilename

public void setFilename(String value)

Sets the Filename property; see getFilename().

Parameters:

value - the new value (not null)

getMicalg

public String getMicalg()

Gets or sets the micalg parameter of a multipart/signed Content-Type header field.

Content-Type: multipart/signed;
   protocol="application/pkcs7-signature";
   micalg=sha-256;
   boundary="example-boundary"

The parameter advertises the message-digest algorithm used by the detached signature. SigningHashAlg is authoritative. When a detached signature is created, getSigningHashAlg() selects the digest and Chilkat replaces any conflicting Micalg value with the corresponding MIME token, such as sha-1, sha-256, sha-384, or sha-512. Setting Micalg alone does not select the cryptographic digest.

Returns:

the value of the Micalg property

setMicalg

public void setMicalg(String value)

Sets the Micalg property; see getMicalg().

Parameters:

value - the new value (not null)

getName

public String getName()

Gets or sets the name parameter of the Content-Type header field. For attachments, getFilename() is generally the primary receiver-facing name.

Setting a non-ASCII value causes Chilkat to emit an RFC 2047 encoded-word in the name= parameter. Setting this property when no media type exists creates a Content-Type field with an empty media type.

Returns:

the value of the Name property

setName

public void setName(String value)

Sets the Name property; see getName().

Parameters:

value - the new value (not null)

getNumDecryptCerts

public int getNumDecryptCerts()

Returns the number of recipient or decryption certificates currently recorded by the most recent S/MIME encryption, decryption, or security-unwrapping operation. A new object returns 0. A successful single-recipient encrypt(Cert) records 1, and successful decryption records the certificate whose private key was used.

Use lastDecryptCert(int, Cert) with a zero-based index to retrieve a recorded certificate. This is a result count; it is not the number of PFX sources or decryption certificates configured on the object.

Returns:

the value of the NumDecryptCerts property (read-only)

getNumHeaderFields

public int getNumHeaderFields()

Returns the number of header-field occurrences in the current part. Duplicate names count separately and retain their order. Valid indexes range from 0 through NumHeaderFields - 1 for use with getHeaderFieldName(int) and getHeaderFieldValue(int).

During MIME parsing, duplicate ordinary fields are retained. Duplicate Content-Type fields are collapsed, with the last value taking effect.

Returns:

the value of the NumHeaderFields property (read-only)

getNumParts

public int getNumParts()

Returns the number of direct child parts. It does not include deeper descendants. Iterate from 0 through NumParts - 1 and call partAt(int, Mime) to traverse the tree.

The object returned by PartAt provides live access to the stored child. Modifying that returned object modifies the parent MIME tree.

Returns:

the value of the NumParts property (read-only)

getNumSignerCerts

public int getNumSignerCerts()

Returns the number of signer certificates currently recorded by the most recent S/MIME signing, signature-verification, or security-unwrapping operation. A new object returns 0. A single-certificate signing method records 1; verify() and unwrapSecurity() replace the count with the signer results from that operation.

A failed call to verify() clears the signer results and sets this property to 0. Use lastSignerCert(int, Cert) with a zero-based index to retrieve a recorded signer certificate.

Returns:

the value of the NumSignerCerts property (read-only)

getOaepHash

public String getOaepHash()

Gets or sets the hash algorithm used by RSAES-OAEP when encrypting the CMS content-encryption key. Supported values are sha1, sha256, sha384, and sha512. The default is sha256. An empty or unrecognized value leaves the current valid setting unchanged.

This property is used only when getOaepPadding() is true. It is independent of getOaepMgfHash(); for example, OAEP may use SHA-256 while MGF1 uses SHA-1.

Returns:

the value of the OaepHash property

setOaepHash

public void setOaepHash(String value)

Sets the OaepHash property; see getOaepHash().

Parameters:

value - the new value (not null)

getOaepMgfHash

public String getOaepMgfHash()

Gets or sets the hash algorithm used by the MGF1 mask generation function within RSAES-OAEP. Supported values are sha1, sha256, sha384, and sha512. The default is sha256. An empty or unrecognized value leaves the current valid setting unchanged.

This property is used only when getOaepPadding() is true and is independent of getOaepHash().

Returns:

the value of the OaepMgfHash property

setOaepMgfHash

public void setOaepMgfHash(String value)

Sets the OaepMgfHash property; see getOaepMgfHash().

Parameters:

value - the new value (not null)

getOaepPadding

public boolean getOaepPadding()

Selects the RSA key-transport padding used when creating encrypted MIME. The default is false, which uses RSAES-PKCS1-v1_5. Set to true to use RSAES-OAEP. Scope. This setting protects the symmetric content-encryption key for an RSA recipient. It does not change the symmetric content algorithm selected by getPkcs7CryptAlg().

Returns:

the value of the OaepPadding property

setOaepPadding

public void setOaepPadding(boolean value)

Sets the OaepPadding property; see getOaepPadding().

Parameters:

value - the new value

getPkcs7CryptAlg

public String getPkcs7CryptAlg()

Gets or sets the symmetric content-encryption algorithm used when creating CMS/PKCS #7 encrypted MIME. Supported input values are aes, aes-gcm, des, 3des, and rc2. The default is aes. The aes-gcm option was added in version 10.0.0.

The getter returns normalized names: after setting aes-gcm it returns aes, and after setting 3des it returns des. The generated CMS data nevertheless uses AES-GCM or 3DES-CBC respectively.

Hybrid encryption. S/MIME encrypts the MIME content with a symmetric content-encryption key. The recipient certificate then protects that content-encryption key. This property selects the symmetric algorithm; getPkcs7KeyLength() selects its key length.

Returns:

the value of the Pkcs7CryptAlg property

setPkcs7CryptAlg

public void setPkcs7CryptAlg(String value)

Sets the Pkcs7CryptAlg property; see getPkcs7CryptAlg().

Parameters:

value - the new value (not null)

getPkcs7KeyLength

public int getPkcs7KeyLength()

Gets or sets the content-encryption key length, in bits, used when creating CMS/PKCS #7 encrypted MIME. The default is 128.

Because this property may be set before getPkcs7CryptAlg(), the setter accepts the union of key lengths that can be valid for any supported symmetric algorithm: 40, 56, 64, 128, 192, and 256. A value outside this set is rejected and the previous value is retained.

Algorithm Normal key lengths

aes or aes-gcm 128, 192, or 256

3des 192

des 40

rc2 40, 56, 64, or 128

Set both properties before encrypting. The property setter rejects only lengths that cannot be valid for any supported algorithm. Applications should select the algorithm and its appropriate key length before calling encrypt(Cert) or encryptN().

Returns:

the value of the Pkcs7KeyLength property

setPkcs7KeyLength

public void setPkcs7KeyLength(int value)

Sets the Pkcs7KeyLength property; see getPkcs7KeyLength().

Parameters:

value - the new value

getProtocol

public String getProtocol()

Gets or sets the protocol parameter of the Content-Type header field. This parameter is commonly used by multipart/signed to identify the media type of the detached signature part.

Content-Type: multipart/signed;
   protocol="application/pkcs7-signature";
   micalg=sha-256;
   boundary="example-boundary"

For this example, Protocol is application/pkcs7-signature.

Returns:

the value of the Protocol property

setProtocol

public void setProtocol(String value)

Sets the Protocol property; see getProtocol().

Parameters:

value - the new value (not null)

getSigningAlg

public String getSigningAlg()

Gets or sets the RSA signature scheme used when creating CMS/PKCS #7 signed MIME. The default and normalized PKCS #1 v1.5 value is PKCS1-V1_5. Set the property to RSASSA-PSS or pss to use RSASSA-PSS; the getter returns RSASSA-PSS.

An empty or unrecognized value selects PKCS1-V1_5. This setting applies only when the signing private key is RSA. It does not select the signature scheme for EC or DSA keys. The property controls signature creation and is not updated during verification; use getLastJsonData(JsonObject) to inspect a verified signature.

Returns:

the value of the SigningAlg property

setSigningAlg

public void setSigningAlg(String value)

Sets the SigningAlg property; see getSigningAlg().

Parameters:

value - the new value (not null)

getSigningHashAlg

public String getSigningHashAlg()

Gets or sets the message-digest algorithm used when creating CMS/PKCS #7 signatures. The default is sha256. Supported values are sha1, sha256, sha384, sha512, md5, and md2. Names are case-insensitive and are returned in lowercase.

An empty or unrecognized value selects sha1. This property controls signature creation only and is not changed when a signature is verified. After verification, call getLastJsonData(JsonObject) to inspect the digest algorithm found in the signed data.

Security guidance. Use a SHA-2 algorithm such as sha256 unless interoperability with a legacy system requires otherwise. MD2, MD5, and SHA-1 are retained for compatibility with older signed messages. Because invalid input falls back to SHA-1, applications should set this property to a known supported value.

Returns:

the value of the SigningHashAlg property

setSigningHashAlg

public void setSigningHashAlg(String value)

Sets the SigningHashAlg property; see getSigningHashAlg().

Parameters:

value - the new value (not null)

getUncommonOptions

public String getUncommonOptions()

Gets or sets a semicolon-delimited or implementation-specific option string used for uncommon compatibility requirements. The default is the empty string, and normal applications should leave it empty. Options placed here may be version-specific and should be used only when directed by Chilkat documentation or support.

Returns:

the value of the UncommonOptions property

setUncommonOptions

public void setUncommonOptions(String value)

Sets the UncommonOptions property; see getUncommonOptions().

Parameters:

value - the new value (not null)

getUnwrapExtras

public boolean getUnwrapExtras()

Controls whether unwrapSecurity() adds informative header fields describing the security layers removed. The default is true.

Header Example value

X-NumPartsSigned 1

X-SignaturesValid yes

X-NumPartsEncrypted 1

X-Decrypted yes

Set to false when the application requires the unwrapped MIME without these additional status headers.

Returns:

the value of the UnwrapExtras property

setUnwrapExtras

public void setUnwrapExtras(boolean value)

Sets the UnwrapExtras property; see getUnwrapExtras().

Parameters:

value - the new value

getUseMmDescription

public boolean getUseMmDescription()

Controls whether Chilkat uses the conventional multipart preamble text This is a multi-part message in MIME format. when serializing a multipart entity. The default is false. The preamble is meaningful only when the multipart has content and is ignored by MIME-aware readers.

Returns:

the value of the UseMmDescription property

setUseMmDescription

public void setUseMmDescription(boolean value)

Sets the UseMmDescription property; see getUseMmDescription().

Parameters:

value - the new value

getUseXPkcs7

public boolean getUseXPkcs7()

Controls whether newly created S/MIME media types use the historical x-pkcs7 names.

Value Generated media types

true (default) application/x-pkcs7-mime and application/x-pkcs7-signature

false application/pkcs7-mime and application/pkcs7-signature

For detached signatures, the selected signature media type is used both for the outer protocol parameter and for the signature part. For opaque signed or encrypted MIME, it controls the application/...pkcs7-mime content type.

Interoperability. The x- forms are widely encountered in existing S/MIME messages. Chilkat recognizes both naming forms.

Returns:

the value of the UseXPkcs7 property

setUseXPkcs7

public void setUseXPkcs7(boolean value)

Sets the UseXPkcs7 property; see getUseXPkcs7().

Parameters:

value - the new value

addContentLength

public void addContentLength()

Computes the byte length of the current entity's serialized MIME body and adds or updates its Content-Length header. The count is based on the transfer-encoded serialized body, not the decoded payload.

For a multipart entity, the count includes boundary delimiter lines, child headers, child bodies, and the closing boundary. Only the current entity's header is updated; child parts do not receive Content-Length fields. Repeated calls recompute the value and leave a single header occurrence.

addDecryptCert

public void addDecryptCert(Cert cert)

Adds cert to the internal collection of certificates available for S/MIME decryption. The certificate must have access to its corresponding private key. Call this method once for each candidate certificate.

The collection is searched by decrypt() and unwrapSecurity(). Other ways to provide decryption credentials include addPfxSourceFile(String, String), addPfxSourceBd(BinData, String), and useCertVault(XmlCertVault).

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addDetachedSignature

public void addDetachedSignature(Cert cert)

Creates an S/MIME detached signature using cert. The certificate itself must have access to its private key. On success, the current object becomes a multipart/signed entity with two direct children:

Part Contents

First The original MIME entity being signed.

Second The CMS/PKCS #7 signature data, normally named smime.p7s.

getSigningHashAlg() selects the digest and generated micalg parameter. For RSA keys, getSigningAlg() selects PKCS #1 v1.5 or RSASSA-PSS. getUseXPkcs7() selects the signature media-type spelling.

Private-key requirement. Adding a matching PFX source does not supply a missing signing key for a public-only Cert. Load the private key into cert or use addDetachedSignaturePk(Cert, PrivateKey). Signing an already signed MIME. Calling this method again creates a new outer multipart/signed layer. It does not add another signer to the existing CMS signer-information set.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addDetachedSignature2

public void addDetachedSignature2(Cert cert,
 boolean transferHeaderFields)

Creates the same detached multipart/signed structure as addDetachedSignature(Cert). cert is the signing certificate and must have access to its private key.

transferHeaderFields Header placement

false Existing message header fields, such as Subject and From, remain on the first signed content part. The new outer multipart has no copies of those fields.

true Existing message header fields are moved to the new outer multipart/signed entity and removed from the first content part.

Parameters:

cert - the cert argument (not null)

transferHeaderFields - the transferHeaderFields argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addDetachedSignaturePk

public void addDetachedSignaturePk(Cert cert,
 PrivateKey privateKey)

Creates a detached S/MIME signature using cert as the signer certificate and privateKey as its associated private key. Use this method when the certificate and private key are supplied separately.

On success, the current object becomes the same two-part multipart/signed structure described by addDetachedSignature(Cert). getSigningHashAlg(), getSigningAlg(), and getUseXPkcs7() control the generated signature.

Parameters:

cert - the cert argument (not null)

privateKey - the privateKey argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addDetachedSignaturePk2

public void addDetachedSignaturePk2(Cert cert,
 PrivateKey privateKey,
 boolean transferHeaderFields)

Creates a detached S/MIME signature using the certificate in cert and the corresponding private key in privateKey. transferHeaderFields controls placement of the existing message header fields:

transferHeaderFields Header placement

false Headers remain on the first signed content part.

true Headers are moved to the new outer multipart/signed entity and removed from the first content part.

This is the separate-private-key counterpart of addDetachedSignature2(Cert, boolean).

Parameters:

cert - the cert argument (not null)

privateKey - the privateKey argument (not null)

transferHeaderFields - the transferHeaderFields argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addEncryptCert

public void addEncryptCert(Cert cert)

Adds cert to the internal recipient-certificate list used by encryptN(). Call this method once for each intended recipient. Encryption uses the public key in each certificate, so recipient private keys are not required at encryption time.

Call clearEncryptCerts() to empty the list.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addHeaderField

public void addHeaderField(String name,
 String value)

Appends a new header field named by name with the value in value. Existing fields having the same case-insensitive name are preserved. An empty value creates a legal empty-valued field.

Chilkat converts spaces in a header name to hyphens, removes embedded CR and LF characters from the value to prevent header injection, and folds long values when serializing.

Replacing versus appending. Use setHeaderField(String, String) to remove all existing occurrences and set one replacement value.

Parameters:

name - the name argument (not null)

value - the value argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addPfxSourceBd

public void addPfxSourceBd(BinData bd,
 String password)

Adds the PKCS #12/PFX bytes in bd to the internal collection of credential sources used by later S/MIME decryption operations. password is the password protecting the PFX data. Call the method once for each PFX source that should be searched.

The source remains configured across subsequent LoadMime calls and repeated decryptions. Chilkat continues searching after a PFX that does not contain the required recipient key.

Not a signing-key fallback. Adding a PFX source does not make a public-only certificate usable by the signing methods. The signing certificate itself must have its private key, or the private key must be supplied explicitly by a method whose name ends in Pk.

Parameters:

bd - the bd argument (not null)

password - the password argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

addPfxSourceFile

public void addPfxSourceFile(String pfxFilePath,
 String password)

Adds the PFX/P12 file at the local filesystem path in pfxFilePath to the internal collection of credential sources used by later S/MIME decryption operations. password is the password protecting the file. Call the method once for each PFX source that should be searched.

The source remains configured across subsequent LoadMime calls and repeated decryptions. Chilkat continues searching after a PFX that does not contain the required recipient key.

Not a signing-key fallback. Adding a PFX source does not make a public-only certificate usable by the signing methods. The signing certificate itself must have its private key, or the private key must be supplied explicitly by a method whose name ends in Pk.

Parameters:

pfxFilePath - the pfxFilePath argument (not null)

password - the password argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

appendPart

public void appendPart(Mime mime)

Appends a copy of mime as the last direct child. Chilkat does not retain a reference to mime, so later changes to mime do not affect the appended part. The same source object may be appended more than once.

If the current object is not multipart, it is converted to multipart/mixed. The complete original entity, including its existing headers and body, becomes part 0; the copy of mime becomes part 1. The new outer entity contains its generated multipart Content-Type.

Editing an appended child. Retrieve it with partAt(int, Mime). The object returned by PartAt is a live child, unlike the copied input to this method.

Parameters:

mime - the mime argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

appendPartFromFile

public void appendPartFromFile(String filename)

Reads the local file at filename, creates an attachment part, and appends it. Filename-extension matching is case-insensitive.

File kind Generated headers

.txt text/plain; charset=windows-1252; format=flowed, 7bit, attachment filename and name

Known binary type, such as .PNG Inferred media type such as image/png, base64, attachment filename and name

Unknown extension application/octet-stream, base64, attachment filename and name

If the current object is not multipart, the same conversion described by appendPart(Mime) occurs. Calling this method on a new empty object therefore creates an empty part 0 and the file attachment as part 1.

Parameters:

filename - the filename argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

asnBodyToXml

public String asnBodyToXml()

Parses the current part's decoded body as ASN.1 DER and returns an XML representation of the ASN.1 structure. This is primarily useful for inspecting CMS/PKCS #7 bodies such as application/pkcs7-mime or application/x-pkcs7-mime.

Content-Type: application/pkcs7-mime; smime-type=signed-data
 Content-Transfer-Encoding: base64
 
 MII...

Diagnostic conversion. The returned XML exposes ASN.1 tags, object identifiers, and values for inspection. It is not the MIME-to-XML representation returned by getXml().

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

clearEncryptCerts

public void clearEncryptCerts()

Clears the internal recipient-certificate list populated by addEncryptCert(Cert). A subsequent call to encryptN() requires certificates to be added again.

containsEncryptedParts

public boolean containsEncryptedParts()

Returns true if the currently visible MIME tree contains a CMS/PKCS #7 encrypted entity. Both application/pkcs7-mime and application/x-pkcs7-mime forms are recognized. Encrypted layers hide their contents. This method examines the MIME structure as it currently exists. It cannot report signed or encrypted entities inside ciphertext until the enclosing encrypted layer is successfully removed.

Returns:

the result; this method never throws ChilkatException

containsSignedParts

public boolean containsSignedParts()

Returns true if the currently visible MIME tree contains a complete detached or opaque CMS/PKCS #7 signed entity. A standalone application/pkcs7-signature or application/x-pkcs7-signature leaf part is not by itself classified as a signed message. Encrypted layers hide their contents. A signature nested inside encrypted data is not visible until the encrypted layer is removed. After a signature is successfully verified and unwrapped, this method returns false because the signed wrapper no longer exists.

Returns:

the result; this method never throws ChilkatException

convert8Bit

public void convert8Bit()

Recursively converts every part whose Content-Transfer-Encoding is 8bit or binary to base64. Both the child object's Encoding property and the serialized header are updated. Parts using 7bit or another encoding are unchanged.

convertToMultipartAlt

public void convertToMultipartAlt()

Wraps the current entity in a new outer multipart/alternative entity. The original entity becomes the first and initially only child.

The new outer entity retains message-level and custom headers such as MIME-Version, Date, Subject, From, To, Content-ID, Content-Location, and custom fields. The original Content-Type, Content-Transfer-Encoding, Content-Disposition, and body move to the first child. An existing charset parameter is retained on the new multipart Content-Type. Calling the method again wraps the existing multipart in another multipart layer; the operation is not idempotent.

Alternative ordering. Additional representations can be appended with appendPart(Mime). Conventionally, alternatives are ordered from least rich to most rich, such as text/plain followed by text/html.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

convertToMultipartMixed

public void convertToMultipartMixed()

Wraps the current entity in a new outer multipart/mixed entity. The original entity becomes the first and initially only child.

The new outer entity retains message-level and custom headers such as MIME-Version, Date, Subject, From, To, Content-ID, Content-Location, and custom fields. The original Content-Type, Content-Transfer-Encoding, Content-Disposition, and body move to the first child. An existing charset parameter is retained on the new multipart Content-Type. Calling the method again wraps the existing multipart in another multipart layer; the operation is not idempotent.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

convertToSigned

public void convertToSigned(Cert cert)

Creates an opaque (attached) S/MIME signature using cert. The certificate itself must have access to its private key. On success, the current MIME entity is replaced by CMS/PKCS #7 signed-data containing both the original MIME bytes and the signature.

The result has no MIME child parts, uses Base64 content-transfer encoding, and has an application/x-pkcs7-mime or application/pkcs7-mime content type according to getUseXPkcs7(). getSigningHashAlg() and, for RSA keys, getSigningAlg() select the signing algorithms.

This differs from addDetachedSignature(Cert), which creates a visible multipart/signed wrapper with a separate signature part.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

convertToSignedPk

public void convertToSignedPk(Cert cert,
 PrivateKey privateKey)

Creates an opaque (attached) S/MIME signature using cert as the signer certificate and privateKey as its associated private key. Use this method when the certificate and private key are supplied separately.

The resulting CMS/PKCS #7 signed-data contains the original MIME entity and its signature, has no MIME child parts, and uses Base64 content-transfer encoding. For a detached multipart/signed result, use addDetachedSignaturePk(Cert, PrivateKey).

Parameters:

cert - the cert argument (not null)

privateKey - the privateKey argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

decrypt

public void decrypt()

Decrypts the current CMS/PKCS #7 encrypted MIME entity and replaces it with the recovered MIME content. Chilkat identifies the intended recipient from the CMS recipient information and searches configured credential sources for the matching certificate and private key.

Source How it is supplied

Explicit certificate addDecryptCert(Cert) or decryptUsingCert(Cert)

PFX/P12 addPfxSourceFile(String, String), addPfxSourceBd(BinData, String), or a DecryptUsingPfx... method

Certificate vault useCertVault(XmlCertVault)

Platform certificate store Windows certificate stores and the macOS Keychain are searched automatically where supported

On success, getNumDecryptCerts() and lastDecryptCert(int, Cert) identify the certificate used, and getLastJsonData(JsonObject) reports the content-encryption algorithm and key size. On failure, the encrypted MIME remains unchanged.

Serialization after decryption. The recovered MIME content is restored semantically, but its generated serialization is not guaranteed to be byte-for-byte identical to the bytes that existed before encryption.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

decrypt2

public void decrypt2(Cert cert,
 PrivateKey privateKey)

Decrypts the current CMS/PKCS #7 encrypted MIME entity using the certificate in cert and its associated private key in privateKey. On success, the encrypted wrapper is replaced by the recovered MIME content, the decryption certificate is available through lastDecryptCert(int, Cert), and operation details are available through getLastJsonData(JsonObject). On failure, the encrypted MIME remains unchanged.

Use this method when the certificate and private key are stored separately. Use decrypt() when Chilkat should locate the credential from configured sources.

Parameters:

cert - the cert argument (not null)

privateKey - the privateKey argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

decryptUsingCert

public void decryptUsingCert(Cert cert)

Decrypts the current CMS/PKCS #7 encrypted MIME entity using cert. The certificate must have access to its corresponding private key; a public-only certificate is insufficient. On success, the encrypted wrapper is replaced by the recovered MIME content and cert is recorded in the decryption results. On failure, the encrypted MIME remains unchanged.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

decryptUsingPfxFile

public void decryptUsingPfxFile(String pfxFilePath,
 String pfxPassword)

Decrypts the current CMS/PKCS #7 encrypted MIME entity using certificates and private keys from the PFX/P12 file at the local filesystem path in pfxFilePath. pfxPassword is the password protecting the file.

On success, the encrypted wrapper is replaced by the recovered MIME content and the matching certificate is available through lastDecryptCert(int, Cert). getLastJsonData(JsonObject) may include both CMS decryption details and information produced while reading the PFX. On failure, the encrypted MIME remains unchanged.

Parameters:

pfxFilePath - the pfxFilePath argument (not null)

pfxPassword - the pfxPassword argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

encrypt

public void encrypt(Cert cert)

Encrypts the current MIME entity for the recipient certificate in cert and replaces it with CMS/PKCS #7 encrypted S/MIME. cert must be RSA-based. Only the recipient's public key is needed to encrypt; the matching private key is required later to decrypt.

The default content encryption is AES-128-CBC. getPkcs7CryptAlg() and getPkcs7KeyLength() select the symmetric algorithm and key length. By default, RSAES-PKCS1-v1_5 transports the content-encryption key; set getOaepPadding() to true to use RSAES-OAEP, with getOaepHash() and getOaepMgfHash() controlling its parameters.

The generated MIME uses Base64 transfer encoding, the filename smime.p7m, and an application/x-pkcs7-mime or application/pkcs7-mime content type according to getUseXPkcs7(). After encryption, getDecryptCertInfo(JsonObject) can report the recipient identifiers stored in the CMS data. If encryption fails, the original MIME remains unchanged.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

encryptN

public void encryptN()

Encrypts the current MIME entity for every certificate previously added with addEncryptCert(Cert). Each recipient receives independently protected access to the same encrypted content.

Add one certificate per intended recipient, call this method, and use clearEncryptCerts() before preparing a different recipient set.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getBodyBd

public void getBodyBd(BinData binDat)

Replaces the contents of binDat with the decoded body bytes of the current part. Existing bytes in binDat are discarded. Base64 and quoted-printable are decoded. MIME headers, multipart boundaries, and child parts are not included.

Parameters:

binDat - the binDat argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getBodyDecoded

public String getBodyDecoded()

Returns the decoded body as text. Chilkat first decodes the Content-Transfer-Encoding and then interprets text according to the declared charset. Use a byte-oriented getter for binary content. A string result cannot reliably represent arbitrary binary bytes or embedded NUL bytes. Use getBodyBd(BinData) or GetBodyBinary for binary payloads.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getBodyEncoded

public String getBodyEncoded()

Returns the current part's transfer-encoded body text without decoding Base64 or quoted-printable. The returned value is Chilkat's normalized serialization of the body, not necessarily the exact text that appeared in the loaded MIME. For example, Base64 padding and line wrapping or quoted-printable spelling may be regenerated.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getDecryptCertInfo

public void getDecryptCertInfo(JsonObject certInfo)

Examines the current encrypted S/MIME entity and writes recipient-certificate identifiers to the JsonObject in certInfo. This can be used to identify which certificate and private key must be made available before calling decrypt() or unwrapSecurity(). A typical result is:

{
   "recipientInfo": [
     {
       "serial": "166FC256FC66A64B20C710F15BFAB63E",
       "issuerCN": "Example Issuing CA"
     }
   ]
 }

The method returns false and writes an empty JSON object when the current MIME entity is not encrypted, including after it has already been decrypted.

No private key is revealed. The encrypted message contains recipient identifiers and encrypted key material, not recipient private keys.

Parameters:

certInfo - the certInfo argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getEntireBody

public String getEntireBody()

Returns the complete serialized body of the current MIME entity. For multipart MIME, this includes boundary delimiters, each child part's headers and body, and the closing boundary. The current entity's own header fields are not included.

Use getBodyDecoded() when the decoded payload of a single part is needed.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getEntireHead

public String getEntireHead()

Returns the complete serialized header section of the current MIME entity. The body and any multipart child content are not included.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getHeaderField

public String getHeaderField(String fieldName)

Returns the value of the first header field whose name matches fieldName case-insensitively. Duplicate later occurrences are not combined. Returns null when no matching field exists.

Parameters:

fieldName - the fieldName argument (not null)

Returns:

the result, or null if not found (no exception is thrown in that case)

getHeaderFieldAttribute

public String getHeaderFieldAttribute(String name,
 String attrName)

Returns an attribute value parsed from the first header field named by name. Both the header name and attrName attribute name are matched case-insensitively. Surrounding quotation marks are removed, and semicolons inside a quoted value are handled as part of the value.

Extended parameters such as filename*=utf-8''r%C3%A9sum%C3%A9.txt are returned in their raw encoded form; this method does not percent-decode or apply the declared charset. Returns null when the field or attribute is absent.

Parameters:

name - the name argument (not null)

attrName - the attrName argument (not null)

Returns:

the result, or null if not found (no exception is thrown in that case)

getHeaderFieldName

public String getHeaderFieldName(int index)

Returns the name of the header-field occurrence at zero-based index. Header order and original casing are preserved for ordinary loaded headers. Use getNumHeaderFields() to determine the valid range.

Parameters:

index - the index argument

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getHeaderFieldValue

public String getHeaderFieldValue(int index)

Returns the unfolded value of the header-field occurrence at zero-based index. Continuation lines are combined into a single value. Use getNumHeaderFields() to determine the valid range.

Parameters:

index - the index argument

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getLastJsonData

public void getLastJsonData(JsonObject json)

Copies structured details from the most recent operation into json when such details are available. Many methods do not produce JSON data.

Operation Typical result

Signing or encryption An empty JSON object.

verify() pkcs7.verify details such as embedded certificates, digest algorithms, signer information, signature algorithm, signing time, message digest, and authenticated attributes.

Decryption pkcs7.decrypt details including the content algorithm and key size. A PFX-based method may also include PKCS #12 parsing details.

unwrapSecurity() May contain both verification and decryption sections when both kinds of security layer were removed.

Read immediately. The information describes the most recent applicable call on this object and can be replaced by a later operation.

Parameters:

json - the json argument (not null)

getMime

public String getMime()

Serializes and returns the complete MIME entity, including headers, body, multipart boundaries, and all descendants. Serialization is normalized. The result is semantically equivalent MIME, not a byte-for-byte copy of loaded input. Chilkat can unfold headers, normalize parameter quoting and transfer encodings, discard multipart preamble and epilogue text, and generate CRLF for headers and multipart framing. Existing body line endings may not always be rewritten.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getMimeBd

public void getMimeBd(BinData bindat)

Serializes the complete MIME entity and appends its bytes to bindat. Existing BinData bytes are preserved. Use this method when arbitrary binary body bytes must not pass through a text string. Serialization is normalized. The result is semantically equivalent MIME, not a byte-for-byte copy of loaded input. Chilkat can unfold headers, normalize parameter quoting and transfer encodings, discard multipart preamble and epilogue text, and generate CRLF for headers and multipart framing. Existing body line endings may not always be rewritten.

Parameters:

bindat - the bindat argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getMimeSb

public void getMimeSb(StringBuilder sb)

Serializes the complete MIME entity and appends it to sb. Existing StringBuilder content is preserved. Serialization is normalized. The result is semantically equivalent MIME, not a byte-for-byte copy of loaded input. Chilkat can unfold headers, normalize parameter quoting and transfer encodings, discard multipart preamble and epilogue text, and generate CRLF for headers and multipart framing. Existing body line endings may not always be rewritten.

Parameters:

sb - the sb argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getSignatureSigningTimeStr

public String getSignatureSigningTimeStr(int index)

Returns the CMS signingTime signed attribute for the signer at zero-based index, formatted as an RFC 822-style date string in GMT. For example:

Wed, 29 Jul 2026 14:32:58 GMT

Call hasSignatureSigningTime(int) first because the attribute is optional. Use getNumSignerCerts() for the signer count.

Signing time is not a trusted timestamp. The CMS signingTime value is supplied by the signer. It is different from a timestamp token issued and signed by a trusted timestamp authority.

Parameters:

index - the index argument

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getStructure

public String getStructure(String fmt)

Returns a concise MIME-tree summary. fmt is case-insensitive. The value xml selects XML output; all other values, including text, an empty string, or an unrecognized value, select the indented text format.

multipart/mixed
     text/plain
     application/octet-stream

<multipart-mixed>
     <text-plain />
     <application-octet-stream />
 </multipart-mixed>

Parameters:

fmt - the fmt argument (not null)

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

getXml

public String getXml()

Converts the MIME tree to Chilkat's XML representation and returns it as a string. Header names become XML element names, structured header parameters become XML attributes, duplicate headers become repeated elements, multipart children are nested in subpart elements, and binary bodies are represented in an encoded textual form. XML round-tripping is semantic. Loading this XML reconstructs an equivalent MIME tree, but it is not byte-preserving and header names are normalized to lowercase.

Returns:

the result (never null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

hasSignatureSigningTime

public boolean hasSignatureSigningTime(int index)

Returns true if the signer at zero-based index has a CMS signingTime signed attribute. Use getNumSignerCerts() for the signer count and getSignatureSigningTimeStr(int) to retrieve the value.

Parameters:

index - the index argument

Returns:

the result; this method never throws ChilkatException

isApplicationData

public boolean isApplicationData()

Returns true when getContentType() begins with application/. It returns false for an empty or malformed media type.

Returns:

the result; this method never throws ChilkatException

isAttachment

public boolean isAttachment()

Returns true when the current part's disposition value is attachment, matched case-insensitively. Parameters such as filename do not affect the test. An inline part remains non-attachment even when it has a filename.

Returns:

the result; this method never throws ChilkatException

isAudio

public boolean isAudio()

Returns true when getContentType() begins with audio/.

Returns:

the result; this method never throws ChilkatException

isEncrypted

public boolean isEncrypted()

Returns true when the current MIME entity is a CMS/PKCS #7 encrypted S/MIME wrapper. Both application/pkcs7-mime and application/x-pkcs7-mime forms are recognized. To search the visible MIME tree rather than only the current entity, use containsEncryptedParts().

Returns:

the result; this method never throws ChilkatException

isHtml

public boolean isHtml()

Returns true when getContentType() is text/html. The ContentType property must contain only the media type; set parameters such as charset separately.

Returns:

the result; this method never throws ChilkatException

isImage

public boolean isImage()

Returns true when getContentType() begins with image/, including values such as image/svg+xml.

Returns:

the result; this method never throws ChilkatException

isMultipart

public boolean isMultipart()

Returns true when getContentType() begins with multipart/.

Returns:

the result; this method never throws ChilkatException

isMultipartAlternative

public boolean isMultipartAlternative()

Returns true when getContentType() is multipart/alternative.

Returns:

the result; this method never throws ChilkatException

isMultipartMixed

public boolean isMultipartMixed()

Returns true when getContentType() is multipart/mixed.

Returns:

the result; this method never throws ChilkatException

isMultipartRelated

public boolean isMultipartRelated()

Returns true when getContentType() is multipart/related.

Returns:

the result; this method never throws ChilkatException

isPlainText

public boolean isPlainText()

Returns true when getContentType() is text/plain.

Returns:

the result; this method never throws ChilkatException

isSigned

public boolean isSigned()

Returns true when the current MIME entity is a complete CMS/PKCS #7 signed S/MIME wrapper, including detached multipart/signed and opaque signed-data forms. A standalone application/pkcs7-signature or application/x-pkcs7-signature leaf part is not by itself classified as a signed message. To search the visible MIME tree, use containsSignedParts().

Returns:

the result; this method never throws ChilkatException

isText

public boolean isText()

Returns true when getContentType() begins with text/.

Returns:

the result; this method never throws ChilkatException

isVideo

public boolean isVideo()

Returns true when getContentType() begins with video/.

Returns:

the result; this method never throws ChilkatException

isXml

public boolean isXml()

Returns true only for text/xml or application/xml. It does not classify structured-suffix media types such as application/soap+xml, application/atom+xml, or image/svg+xml as XML.

Returns:

the result; this method never throws ChilkatException

lastDecryptCert

public void lastDecryptCert(int index,
 Cert cert)

Loads into cert the decryption certificate at zero-based index from the most recent successful decryption or security-unwrapping operation. Valid indexes range from 0 through getNumDecryptCerts() - 1. The returned certificate has access to the private key used for decryption.

An invalid index returns false and leaves cert unchanged.

Parameters:

index - the index argument

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

lastSignerCert

public void lastSignerCert(int index,
 Cert cert)

Loads into cert the signer certificate at zero-based index from the most recent successful signature-verification or security-unwrapping operation. Valid indexes range from 0 through getNumSignerCerts() - 1. The returned certificate normally contains only the public key; it does not gain access to the signer's private key.

An invalid index returns false and leaves cert unchanged. A later failed call to verify() clears the signer results.

Parameters:

index - the index argument

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadMime

public void loadMime(String mimeMsg)

Parses the complete MIME text in mimeMsg and replaces the current object's headers, body, and multipart tree. A successful call always replaces the previous MIME.

If no blank line separates headers from the body, lines that appear header-like are parsed as headers and the body is empty. Data after the header/body separator belongs to the body.

Permissive parser and normalized output. Chilkat accepts many imperfect messages. Observed behavior includes ignoring malformed header lines and leading non-header text, using the last duplicate Content-Type, repairing a missing multipart closing delimiter during serialization, treating unmatched boundary-like text as an ordinary body, and tolerating malformed Base64 or quoted-printable. LF-only and CR-only input are accepted; generated headers and multipart framing use CRLF. Loading and reserializing is therefore not guaranteed to reproduce the original bytes, and multipart preamble and epilogue text are not retained. Text input is not a raw-byte container. Use loadMimeBd(BinData) or LoadMimeBytes for arbitrary 8-bit bytes or embedded NUL bytes.

Parameters:

mimeMsg - the mimeMsg argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadMimeBd

public void loadMimeBd(BinData bindat)

Parses complete MIME bytes from bindat and replaces the current MIME on success. This is the preferred loader when the MIME can contain arbitrary 8-bit body bytes or embedded NUL bytes. Parsing tolerance and serialization normalization are the same as loadMime(String).

Parameters:

bindat - the bindat argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadMimeFile

public void loadMimeFile(String fileName)

Reads and parses the complete MIME entity from the local file at fileName. A successful call replaces the current MIME. If the file cannot be opened, the method returns false and preserves the existing object unchanged.

Parsing tolerance and serialization normalization are the same as loadMime(String).

Parameters:

fileName - the fileName argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadMimeSb

public void loadMimeSb(StringBuilder sb)

Parses complete MIME text from sb and replaces the current MIME on success. Parsing tolerance and serialization normalization are the same as loadMime(String). Use byte input for arbitrary MIME bytes. A StringBuilder is text-oriented. Use loadMimeBd(BinData) for binary MIME containing arbitrary 8-bit values or NUL bytes.

Parameters:

sb - the sb argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadXml

public void loadXml(String xml)

Reconstructs a MIME tree from Chilkat's MIME XML in xml. On success, the current object is replaced. If the XML is invalid, the method returns false and preserves the existing MIME unchanged.

The reconstructed MIME is semantically equivalent but not byte-identical to the MIME that produced the XML. Header names are normalized to lowercase.

Parameters:

xml - the xml argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

loadXmlFile

public void loadXmlFile(String fileName)

Reads Chilkat MIME XML from the local file at fileName and reconstructs the MIME tree. On success, the current object is replaced. If the file cannot be opened or the XML is invalid, the method returns false and preserves the existing MIME unchanged. Header names are normalized to lowercase during reconstruction.

Parameters:

fileName - the fileName argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

newMessageRfc822

public void newMessageRfc822(Mime mimeObject)

Clears the current object and initializes it as message/rfc822. Its body is a serialized copy of mimeObject at the time of the call. Later modifications to mimeObject do not change the embedded message.

Parameters:

mimeObject - the mimeObject argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

newMultipartAlternative

public void newMultipartAlternative()

Initializes an empty multipart/alternative entity. Clears all existing headers, body content, and child parts. The new object contains only a multipart Content-Type with an automatically generated boundary, has zero parts, and does not automatically add MIME-Version.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

newMultipartMixed

public void newMultipartMixed()

Initializes an empty multipart/mixed entity. Clears all existing headers, body content, and child parts. The new object contains only a multipart Content-Type with an automatically generated boundary, has zero parts, and does not automatically add MIME-Version.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

newMultipartRelated

public void newMultipartRelated()

Initializes an empty multipart/related entity. Clears all existing headers, body content, and child parts. The new object contains only a multipart Content-Type with an automatically generated boundary, has zero parts, and does not automatically add MIME-Version.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

partAt

public void partAt(int index,
 Mime subPart)

Provides live access to the direct child at zero-based index through subPart. Modifying subPart after a successful call modifies the child stored in the parent MIME tree.

Valid indexes range from 0 through getNumParts() - 1. An invalid index returns false and preserves subPart unchanged.

Different from AppendPart. appendPart(Mime) stores a copy of its argument. This method exposes the actual stored child.

Parameters:

index - the index argument

subPart - the subPart argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

partsToFiles

public void partsToFiles(String path,
 StringTable st)

Recursively traverses the MIME tree and saves each part having a nonempty filename parameter to the existing directory in path. A name parameter alone is not used as a fallback. The disposition may be attachment or inline; a filename is what controls extraction.

• Only the final path component of a MIME filename is used. Directory components, absolute paths, and .. traversal are discarded.
• On Windows, invalid filename characters are replaced with underscores.
• Duplicate filenames target the same path; later parts overwrite earlier parts.
• st is appended to rather than cleared. Each added entry is the full path actually written, including any sanitized filename.
• The destination directory is not created. If it does not exist, the method returns false, creates no files, and appends nothing to st.

Treat MIME filenames as untrusted. Use a controlled destination directory and apply any application-specific policy for file types, size limits, overwriting, and renaming.

Parameters:

path - the path argument (not null)

st - the st argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

removeHeaderField

public void removeHeaderField(String fieldName,
 boolean bAllOccurrences)

Removes fields whose name matches fieldName case-insensitively. If bAllOccurrences is false, only the first matching occurrence is removed. If bAllOccurrences is true, all matching occurrences are removed. Remaining fields retain their relative order.

Parameters:

fieldName - the fieldName argument (not null)

bAllOccurrences - the bAllOccurrences argument

removePart

public void removePart(int index)

Removes the direct child at zero-based index. Valid indexes range from 0 through getNumParts() - 1. An out-of-range index returns false and leaves the tree unchanged.

Parameters:

index - the index argument

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

saveBody

public void saveBody(String filename)

Writes the decoded body bytes of the current part to the local path in filename. Base64 and quoted-printable are decoded. MIME headers and multipart framing are not written. File behavior. Existing files are overwritten. Parent directories are not created, and passing a directory as the destination fails. On Windows, an existing read-only file is replaced and the read-only attribute is removed.

Parameters:

filename - the filename argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

saveMime

public void saveMime(String filename)

Serializes the complete MIME entity and writes it to the local path in filename, including headers, body, multipart boundaries, and all descendants. Serialization is normalized. The result is semantically equivalent MIME, not a byte-for-byte copy of loaded input. Chilkat can unfold headers, normalize parameter quoting and transfer encodings, discard multipart preamble and epilogue text, and generate CRLF for headers and multipart framing. Existing body line endings may not always be rewritten. File behavior. Existing files are overwritten. Parent directories are not created, and passing a directory as the destination fails. On Windows, an existing read-only file is replaced and the read-only attribute is removed.

Parameters:

filename - the filename argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

saveXml

public void saveXml(String filename)

Writes Chilkat's MIME XML representation to the local path in filename. The file can be loaded by loadXmlFile(String). File behavior. Existing files are overwritten. Parent directories are not created, and passing a directory as the destination fails. On Windows, an existing read-only file is replaced and the read-only attribute is removed.

Parameters:

filename - the filename argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBody

public void setBody(String str)

Sets the current part's body from str while preserving existing content headers such as Content-Type, charset, and Content-Transfer-Encoding. Multipart entities serialize their child parts. Calling this method on a multipart object changes what the body getter methods return, but the assigned body is not included in the serialized multipart output while child parts are present. Build multipart content through appendPart(Mime) and partAt(int, Mime).

Parameters:

str - the str argument (not null)

setBodyBd

public void setBodyBd(BinData bd)

Sets the decoded body bytes from bd, changes Content-Transfer-Encoding to base64, and preserves the bytes exactly. It does not set a Content-Type, disposition, filename, or name; set those separately when needed.

Parameters:

bd - the bd argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBodyFromEncoded

public void setBodyFromEncoded(String encoding,
 String str)

Sets the body from transfer-encoded text. encoding must be base64 or quoted-printable; other values, including 7bit, 8bit, binary, an unknown name, or an empty string, cause failure.

Base64 whitespace is accepted and the stored representation is normalized. Invalid Base64 causes the method to return false. On any failure, all existing headers and body content are preserved unchanged.

Do not encode twice. str must already be in the encoding named by encoding. To provide decoded bytes, use setBodyBd(BinData) or SetBodyFromBinary.

Parameters:

encoding - the encoding argument (not null)

str - the str argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBodyFromFile

public void setBodyFromFile(String fileName)

Reads the local file at fileName and replaces the current part's body and content headers according to the filename extension.

File kind Result

.txt text/plain; charset=windows-1252; format=flowed, 7bit

.html text/html; charset=windows-1252, 7bit

Unknown extension application/octet-stream, base64, attachment, and filename/name parameters based on the local filename

If the file cannot be opened, the method returns false and preserves the existing MIME unchanged.

Parameters:

fileName - the fileName argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBodyFromHtml

public void setBodyFromHtml(String str)

Sets str as HTML and changes the media type to text/html. For ASCII input, Chilkat uses Content-Transfer-Encoding: 7bit and does not add a charset. Existing unrelated headers are preserved.

Parameters:

str - the str argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBodyFromPlainText

public void setBodyFromPlainText(String str)

Sets str as plain text. For ASCII input, Chilkat sets Content-Type: text/plain; format=flowed and Content-Transfer-Encoding: 7bit without a charset. For non-ASCII UTF-8 input, it sets charset=utf-8 and uses 8bit. Existing unrelated headers are preserved.

Parameters:

str - the str argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setBodyFromXml

public void setBodyFromXml(String str)

Sets str as XML, changes the media type to text/xml, and selects a transfer encoding appropriate for the text. For ASCII input, Chilkat uses 7bit and does not add a charset.

The XML declaration's encoding value is not copied to the MIME charset parameter.

Different from LoadXml. This method places an XML document in the MIME body. loadXml(String) reconstructs an entire MIME object from Chilkat MIME XML.

Parameters:

str - the str argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setHeaderField

public void setHeaderField(String name,
 String value)

Sets one header field named by name. Matching is case-insensitive. All existing occurrences are removed and one replacement is inserted. If no field exists, a new one is added. Passing an empty value removes all matching occurrences rather than creating an empty-valued field.

Use addHeaderField(String, String) to append another occurrence or to create an empty-valued field.

Parameters:

name - the name argument (not null)

value - the value argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

setVerifyCert

public void setVerifyCert(Cert cert)

Supplies cert as a signer-certificate fallback for subsequent signature verification. This is useful when the CMS/PKCS #7 signature does not embed the signer certificate and Chilkat cannot otherwise locate it. Only the public key is required. This does not require a particular signer. An embedded signer certificate takes precedence. If the CMS signature embeds the correct signer certificate, verification can succeed even when cert is an unrelated certificate, and lastSignerCert(int, Cert) returns the embedded certificate. To enforce signer identity, verify first and then compare the returned signer certificate using application-defined criteria such as its serial number, fingerprint, subject, issuer, or trusted chain.

Parameters:

cert - the cert argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

unwrapSecurity

public void unwrapSecurity()

Removes supported S/MIME security layers and restores the underlying MIME content. It handles both common layer orders: a message signed and then encrypted, and a message encrypted and then signed. It continues through nested top-level layers until no additional supported security wrapper remains.

After a successful call, getNumSignerCerts() and lastSignerCert(int, Cert) identify verified signers, while getNumDecryptCerts() and lastDecryptCert(int, Cert) identify decryption certificates. getLastJsonData(JsonObject) may contain both pkcs7.verify and pkcs7.decrypt details.

Additional result headers. When getUnwrapExtras() is true, Chilkat adds headers such as X-NumPartsSigned, X-SignaturesValid, X-NumPartsEncrypted, and X-Decrypted. Set it to false to omit these headers.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

urlEncodeBody

public void urlEncodeBody(String charset)

Replaces the current body with an application/x-www-form-urlencoded-style representation using the character set named by charset. Spaces become +, a literal plus becomes %2B, non-ASCII bytes become %HH sequences, and separators such as & and = remain unchanged.

Input:  a b+c&d=e
 Output: a+b%2Bc&d=e

The MIME content headers are not changed. If the named character set is unsupported, the body remains unchanged.

Not a MIME transfer encoding. This operation is distinct from base64 and quoted-printable.

Parameters:

charset - the charset argument (not null)

useCertVault

public void useCertVault(XmlCertVault vault)

Sets vault as the certificate vault used to locate certificates and private keys for S/MIME encryption, decryption, signing, and verification. Only one vault is active; each call replaces the previously configured vault.

Use XmlCertVault when credentials are maintained independently of platform certificate stores or individual PFX sources.

Parameters:

vault - the vault argument (not null)

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

verify

public void verify()

Verifies the current CMS/PKCS #7 signed MIME entity and removes the signature wrapper. Both detached multipart/signed messages and opaque CMS signed-data are supported. The method works with signed MIME loaded from serialized input as well as MIME signed by the current object.

On success, the object is restored to the MIME structure and content that was signed, getNumSignerCerts() reports the verified signer count, lastSignerCert(int, Cert) returns the signer certificate, and getLastJsonData(JsonObject) reports CMS verification details. A detached signature can restore the original serialization exactly, but opaque signed-data restoration is semantic and is not guaranteed to reproduce byte-for-byte identical MIME serialization.

On failure, the signed wrapper remains unchanged, no content is unwrapped, and the signer-result count is cleared to 0.

SetVerifyCert is a fallback, not a signer restriction. When the CMS data embeds a usable signer certificate, Chilkat uses that embedded certificate. Verification can therefore succeed even when setVerifyCert(Cert) was given an unrelated certificate. Enforce signer identity after verification by examining lastSignerCert(int, Cert). What verification proves. Cryptographic verification establishes that the signed bytes have not changed and that the signature matches the signer certificate. Application trust decisions may additionally require validating the certificate chain, identity, usage, validity period, and revocation status.

Throws:

ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why