MailReader Class

Properties   Methods   Events   Config Settings   Errors  

The MailReader class implements parsing and decryption of e-mail messages.

Syntax

secureblackbox.Mailreader

Remarks

MailReader parses and decrypts e-mail messages, as well as verifies electronic signatures.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

Attachments Property (MailReader Class)

Provides access to Message's attachments.

Syntax

public MailAttachmentList getAttachments();

Remarks

Use this property to access the attachments of the loaded message.

This property is read-only.

Bcc Property (MailReader Class)

The contents of the BCC header field of the Message.

Syntax

public MailAddressList getBcc();

Remarks

The BCC header field contains the addresses of secondary recipients of the message whose addresses are not to be revealed to other recipients of the message.

Mail servers remove the BCC header when processing the message and use its value for dispatching the message only.

This property is read-only.

BlockedCertificates Property (MailReader Class)

The certificates that must be rejected as trust anchors.

Syntax

public CertificateList getBlockedCertificates();


public void setBlockedCertificates(CertificateList blockedCertificates);

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Cc Property (MailReader Class)

The value of the CC header field of the Message.

Syntax

public MailAddressList getCc();

Remarks

The CC field contains the addresses of secondary recipients of the message.

This property is read-only.

DecryptionCertificate Property (MailReader Class)

The certificate to be used for decryption.

Syntax

public Certificate getDecryptionCertificate();


public void setDecryptionCertificate(Certificate decryptionCertificate);

Remarks

Use this property to provide the decryption certificate. The decryption certificate must have a private key associated with it.

This property is not available at design time.

ExternalCrypto Property (MailReader Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on OnExternalSign event) and asynchronous (based on DC protocol and DCAuth signing component).

This property is read-only.

FIPSMode Property (MailReader Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

From Property (MailReader Class)

Contains the value of the From header of the Message.

Syntax

public MailAddressList getFrom();

Remarks

This field contains address(es) of message author(s). If the actual sender is not the author of the message, the sender is provided separately via Sender property.

This property is read-only.

IgnoreChainValidationErrors Property (MailReader Class)

Makes the class tolerant to chain validation errors.

Syntax

public boolean isIgnoreChainValidationErrors();


public void setIgnoreChainValidationErrors(boolean ignoreChainValidationErrors);

Default Value

False

Remarks

If this property is set to True, any errors emerging during certificate chain validation will be ignored. This setting may be handy if the purpose of validation is the creation of an LTV signature, and the validation is performed in an environment that doesn't trust the signer's certificate chain.

KnownCertificates Property (MailReader Class)

Additional certificates for chain validation.

Syntax

public CertificateList getKnownCertificates();


public void setKnownCertificates(CertificateList knownCertificates);

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of certificates to be added to this collection is roughly equivalent to that of Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

KnownCRLs Property (MailReader Class)

Additional CRLs for chain validation.

Syntax

public CRLList getKnownCRLs();


public void setKnownCRLs(CRLList knownCRLs);

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

KnownOCSPs Property (MailReader Class)

Additional OCSP responses for chain validation.

Syntax

public OCSPResponseList getKnownOCSPs();


public void setKnownOCSPs(OCSPResponseList knownOCSPs);

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Message Property (MailReader Class)

The message that is currently stored in the class.

Syntax

public MailMessage getMessage();


public void setMessage(MailMessage message);

Remarks

Use this property to access the message that has been processed and populated by class.

This property is not available at design time.

OfflineMode Property (MailReader Class)

Switches the class to the offline mode.

Syntax

public boolean isOfflineMode();


public void setOfflineMode(boolean offlineMode);

Default Value

False

Remarks

When working in offline mode, the component restricts itself from using any online revocation information sources, such as CRL or OCSP responders.

Offline mode may be useful if there is a need to verify the completeness of validation information included within the signature or provided via KnownCertificates, KnownCRLs, and other related properties.

OtherHeaders Property (MailReader Class)

Contains secondary headers of the mail message.

Syntax

public StringNameValuePairList getOtherHeaders();

Remarks

Use this property to access the headers that have not been published in first-level object's properties.

This property is read-only.

Profile Property (MailReader Class)

Specifies a pre-defined profile to apply when creating the signature.

Syntax

public String getProfile();


public void setProfile(String profile);

Default Value

""

Remarks

Advanced signatures come in many variants, which are often defined by parties that needs to process them or by local standards. SecureBlackbox profiles are sets of pre-defined configurations which correspond to particular signature variants. By specifying a profile, you are pre-configuring the component to make it produce the signature that matches the configuration corresponding to that profile.

Proxy Property (MailReader Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

ReplyTo Property (MailReader Class)

The value of the Reply-To header field of the Message.

Syntax

public MailAddressList getReplyTo();

Remarks

This field contains the addresses to which the replies to this message should be sent. This field is optional. If not specified, the replies should be sent to the addresses specified in the From field.

This property is read-only.

RevocationCheck Property (MailReader Class)

Specifies the kind(s) of revocation check to perform.

Syntax

public int getRevocationCheck();


public void setRevocationCheck(int revocationCheck);


Enumerated values:
  public final static int crcNone = 0;
  public final static int crcAuto = 1;
  public final static int crcAllCRL = 2;
  public final static int crcAllOCSP = 3;
  public final static int crcAllCRLAndOCSP = 4;
  public final static int crcAnyCRL = 5;
  public final static int crcAnyOCSP = 6;
  public final static int crcAnyCRLOrOCSP = 7;
  public final static int crcAnyOCSPOrCRL = 8;

Default Value

1

Remarks

Revocation checking is necessary to ensure the integrity of the chain and obtain up-to-date certificate validity and trustworthiness information.

Certificate Revocation Lists (CRL) and Online Certificate Status Protocol (OCSP) responses serve the same purpose of ensuring that the certificate had not been revoked by the Certificate Authority (CA) at the time of use. Depending on your circumstances and security policy requirements, you may want to use either one or both of the revocation information source types.

This setting controls the way the revocation checks are performed. Typically certificates come with two types of revocation information sources: CRL (certificate revocation lists) and OCSP responders. CRLs are static objects periodically published by the CA at some online location. OCSP responders are active online services maintained by the CA that can provide up-to-date information on certificate statuses in near real time.

There are some conceptual differences between the two. CRLs are normally larger in size. Their use involves some latency because there is normally some delay between the time when a certificate was revoked and the time the subsequent CRL mentioning that is published. The benefits of CRL is that the same object can provide statuses for all certificates issued by a particular CA, and that the whole technology is much simpler than OCSP (and thus is supported by more CAs).

This setting lets you adjust the validation course by including or excluding certain types of revocation sources from the validation process. The crcAnyOCSPOrCRL setting (give preference to faster OCSP route and only demand one source to succeed) is a good choice for most of typical validation environments. The "crcAll*" modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

SecurityInfo Property (MailReader Class)

Contains the Message's security info.

Syntax

public MailSecurityInfo getSecurityInfo();

Remarks

Use this property to check the security information about the Message, such as whether the message is signed or the encryption algorithm used.

This property is read-only.

Sender Property (MailReader Class)

The value of the Sender header field of the Message.

Syntax

public MailAddress getSender();

Remarks

This field specifies the mailbox of the agent responsible for the actual transmission of this message.

If the originator of the message can be indicated by a single mailbox and both the author and the transmitter are the same entity, the "Sender:" field is not used ("From:" used instead).

This property is read-only.

SendTo Property (MailReader Class)

The value of the To header field of the Message.

Syntax

public MailAddressList getSendTo();

Remarks

This field specifies the address(es) of the primary recipient(s) of the message.

This property is read-only.

SigningCertificate Property (MailReader Class)

The certificate of the signature creator.

Syntax

public Certificate getSigningCertificate();

Remarks

Use this property to access the certificate that was used to create the signature.

This property is read-only and not available at design time.

SocketSettings Property (MailReader Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

TLSSettings Property (MailReader Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

TrustedCertificates Property (MailReader Class)

A list of trusted certificates for chain validation.

Syntax

public CertificateList getTrustedCertificates();


public void setTrustedCertificates(CertificateList trustedCertificates);

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same than that of Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

UsedCertificates Property (MailReader Class)

Contains a list of certificates used during the chain validation routine.

Syntax

public CertificateList getUsedCertificates();

Remarks

Use this property to access the list of certificates that were used during the chain validation.

This property is read-only and not available at design time.

ValidationMoment Property (MailReader Class)

The time point at which signature validity is to be established.

Syntax

public String getValidationMoment();


public void setValidationMoment(String validationMoment);

Default Value

""

Remarks

Use this property to specify the moment in time at which signature validity should be established. The time is in UTC. Leave the setting empty to stick to the default moment (either signature creation time, or current time).

The validity of the same signature may differ depending on the time point chosen due to temporal changes in chain validities, revocation statuses, and timestamp times.

Config Method (Mailreader Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (Mailreader Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insencitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

FindAttachment Method (Mailreader Class)

Looks up a Message's attachment by its ID.

Syntax

public int findAttachment(String ID);

Remarks

Use this method to find the attachment by its ID.

LoadFromBytes Method (Mailreader Class)

Loads an e-mail message from a byte array.

Syntax

public void loadFromBytes(byte[] messageBytes);

Remarks

Use this method to load a message from a byte array and process it. Once the message has been loaded, use Message to access its properties.

LoadFromFile Method (Mailreader Class)

Loads an e-mail message from a file.

Syntax

public void loadFromFile(String filename);

Remarks

Use this method to load a message from a file and process it. Once the message has been loaded, use Message to access its properties.

LoadFromStream Method (Mailreader Class)

Loads an e-mail message from a stream.

Syntax

public void loadFromStream(java.io.InputStream stream);

Remarks

Use this method to load a message from a stream and process it. Once the message has been loaded, use Message to access its properties.

ChainValidated Event (Mailreader Class)

Reports the completion of a certificate chain validation.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void chainValidated(MailreaderChainValidatedEvent e) {}
  ...
}

public class MailreaderChainValidatedEvent {
  public String subjectRDN;
  public int validationResult;
  public int validationDetails;
}

Remarks

This event is fired when a certificate chain validation routine completes. SubjectRDN identifies the owner of the validated certificate.

ValidationResult set to 0 (zero) indicates successful chain validation.

DecryptionInfoNeeded Event (Mailreader Class)

Asks the application to provide a decryption certificate.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void decryptionInfoNeeded(MailreaderDecryptionInfoNeededEvent e) {}
  ...
}

public class MailreaderDecryptionInfoNeededEvent {
  public String issuerRDN;
  public byte[] serialNumber;
  public byte[] subjectKeyID;
}

Remarks

This event is fired when the component needs a decryption certificate. Use the provided values to look up the certificate, and assign it to DecryptionCertificate property.

Note that the decryption certificate must have an associated private key.

Error Event (Mailreader Class)

Reports information about errors during e-mail message loading, parsing or saving.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void error(MailreaderErrorEvent e) {}
  ...
}

public class MailreaderErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error.

ExternalDecrypt Event (Mailreader Class)

Handles remote or external decryption.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void externalDecrypt(MailreaderExternalDecryptEvent e) {}
  ...
}

public class MailreaderExternalDecryptEvent {
  public String operationId;
  public String algorithm;
  public String pars;
  public String encryptedData;
  public String data;
}

Remarks

Assign a handler to this event if you need to delegate a low-level decryption operation to an external, remote, or custom decryption engine. The handler receives a encrypted value in the EncryptedData parameter, and is expected to decrypt it and place the decrypted value into the Data parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. Algorithm specifies the encryption algorithm being used, and Pars contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for EncryptedData, Data, and Pars parameters. If your decryption engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the decryption.

A sample data encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

Notification Event (Mailreader Class)

This event notifies the application about an underlying control flow event.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void notification(MailreaderNotificationEvent e) {}
  ...
}

public class MailreaderNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

SignatureFound Event (Mailreader Class)

Signifies the start of signature validation.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void signatureFound(MailreaderSignatureFoundEvent e) {}
  ...
}

public class MailreaderSignatureFoundEvent {
  public String issuerRDN;
  public byte[] serialNumber;
  public byte[] subjectKeyID;
  public boolean certFound;
  public boolean validateSignature;
  public boolean validateChain;
}

Remarks

This event tells the application that signature validation is about to start, and provides the details about the signer's certificate via its IssuerRDN, SerialNumber, and SubjectKeyID parameters. It fires for every signature located in the verified document or message.

The CertFound is set to True if the class has found the needed certificate in one of the known locations, and to False otherwise, in which case you must provide it manually via KnownCertificates property.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. Separate validation results are reported for each, with SignatureValidationResult and ChainValidationResult properties respectively.

Use the ValidateSignature and ValidateChain parameters to tell the verifier which stages to include in the validation.

SignatureValidated Event (Mailreader Class)

Marks the completion of the signature validation routine.

Syntax

public class DefaultMailreaderEventListener implements MailreaderEventListener {
  ...
  public void signatureValidated(MailreaderSignatureValidatedEvent e) {}
  ...
}

public class MailreaderSignatureValidatedEvent {
  public String issuerRDN;
  public byte[] serialNumber;
  public byte[] subjectKeyID;
  public int validationResult;
}

Remarks

This event is fired upon the completion of the signature validation routine, and reports the respective validation result.

Use the IssuerRDN, SerialNumber, and/or SubjectKeyID parameters to identify the signing certificate.

ValidationResult is set to 0 if the validation has been successful, or to a non-zero value in case of a validation failure.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

public Certificate( bytes,  startIndex,  count,  password);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( bytes,  startIndex,  count);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

public Certificate( path,  password);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certPath,  keyPath,  password);

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

public Certificate( path);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

public Certificate( stream);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public Certificate( stream,  password);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certStream,  keyStream,  password);

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

public Certificate();

Creates a new object with default field values.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

public CRL( bytes,  startIndex,  count);

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

public CRL( location);

Creates a CRL object by downloading it from a remote location.

public CRL( stream);

Creates a CRL object from data contained in a stream.

public CRL();

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

public ExternalCrypto();

public MailAddress( address);

Creates a new e-mail address object.

public MailAddress( displayName,  address);

Creates a new e-mail address object from an address and a display name.

MailAttachment Type

Represents an attachment to an e-mail message.

Remarks

This object is a container for message attachments.

Fields

public MailAttachment( contentType);

Creates an empty mail attachment object.

MailMessage Type

Represents an e-mail message.

Remarks

This object is a container for an e-mail message.

A message consists of a header and a body. The header, in turn, consists of several header fields. The names, syntax, and expected contents of the header fields are standardized.

The message body can contain anything you like (a message may not even have a body at all).

Fields

public MailMessage();

public MailSecurityInfo();

public OCSPResponse( bytes,  startIndex,  count);

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

public OCSPResponse( location);

Downloads an OCSP response from a remote location.

public OCSPResponse( stream);

Initializes the response with the data from a stream.

public OCSPResponse();

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

public ProxySettings();

public SocketSettings();

public StringNameValuePair( name,  value);

Creates a name-value pair from a name and a value.

public StringNameValuePair();

Creates an empty name-value object.

TLSSettings Type

A container for TLS connection settings.

Remarks

TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

public TLSSettings();

Config Settings (Mailreader Class)

MailReader Config Settings

Base Config Settings

Trappable Errors (Mailreader Class)

MailReader Errors