MessageEncryptor Class

Properties   Methods   Events   Config Settings   Errors  

The MessageEncryptor class encrypts data and stores it in the PKCS#7 format.

Syntax

secureblackbox.Messageencryptor

Remarks

PKCS#7 (Public Key Cryptography Standard #7) is a common format used to store encrypted and signed data. It is used by a variety of protocols, including S/MIME and CMS.

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.

BitsInKey Property (MessageEncryptor Class)

The length of the encryption key.

Syntax

public int getBitsInKey();


public void setBitsInKey(int bitsInKey);

Default Value

0

Remarks

When using a variable-key encryption algorithm (typical examples are RC4, RC2, and Blowfish), provide the desired key length via this property.

This value is ignored if a fixed-key algorithm (such as AES128 or 3DES) is used.

EncryptionAlgorithm Property (MessageEncryptor Class)

The symmetric key algorithm to use for encryption.

Syntax

public String getEncryptionAlgorithm();


public void setEncryptionAlgorithm(String encryptionAlgorithm);

Default Value

"AES128"

Remarks

Use this property to specify the symmetric algorithm to encrypt the data with.

EncryptionCertificate Property (MessageEncryptor Class)

The certificate to use for encryption.

Syntax

public Certificate getEncryptionCertificate();


public void setEncryptionCertificate(Certificate encryptionCertificate);

Remarks

Use this property to specify the certificate to be used for encryption. This is a "recipient's" certificate, and as such it does not need to have an associated private key.

If the certificate is provided, an output message of EnvelopedData type will be created. The private key corresponding to the encryption certificate will be needed to decrypt it.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

EncryptionType Property (MessageEncryptor Class)

Specifies the kind of encrypted message to create.

Syntax

public int getEncryptionType();


public void setEncryptionType(int encryptionType);


Enumerated values:
  public final static int metUnknown = 0;
  public final static int metCertEncrypted = 1;
  public final static int metKeyEncrypted = 2;
  public final static int metCertEncryptedAndAuthenticated = 3;

Default Value

1

Remarks

Possible values:

FIPSMode Property (MessageEncryptor Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (MessageEncryptor Class)

Use this property to pass the input to class in byte array form.

Syntax

public byte[] getInputBytes();


public void setInputBytes(byte[] inputBytes);

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

InputFile Property (MessageEncryptor Class)

A path to the source file.

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

Use this property to provide a path to the file containing the data to be encrypted.

InputStream Property (MessageEncryptor Class)

A stream containing the data to be encrypted.

Syntax

public java.io.InputStream getInputStream();


public void setInputStream(java.io.InputStream inputStream);

Default Value

null

Remarks

Use this property to provide the data to be encrypted from a stream.

This property is not available at design time.

Key Property (MessageEncryptor Class)

The symmetric key to use for encryption.

Syntax

public byte[] getKey();


public void setKey(byte[] key);

Remarks

Use this property to provide a symmetric key to use for encryption. If the symmetric key is provided, an output message of EncryptedData type will be formed. The recipient of this message will need to have the same key to decrypt it.

This property is not available at design time.

OutputBytes Property (MessageEncryptor Class)

Use this property to read the output the class object has produced.

Syntax

public byte[] getOutputBytes();

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the OutputFile and OutputStream properties had not been assigned.

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

OutputFile Property (MessageEncryptor Class)

A path to the output file.

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

Use this property to specify the file to save the encrypted message to.

OutputStream Property (MessageEncryptor Class)

A stream where the encrypted data should be written.

Syntax

public java.io.OutputStream getOutputStream();


public void setOutputStream(java.io.OutputStream outputStream);

Default Value

null

Remarks

Use this property to specify the stream to save the encrypted message to.

This property is not available at design time.

SignedAttributes Property (MessageEncryptor Class)

Custom signature attributes to be covered by the electronic signature.

Syntax

public SignatureAttributeList getSignedAttributes();

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as signed attributes are covered by the signature.

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

Please refer to the SignatureAttribute type for a complete list of fields.

UnsignedAttributes Property (MessageEncryptor Class)

Custom unsigned attributes to be included in the electronic signature.

Syntax

public SignatureAttributeList getUnsignedAttributes();

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as unsigned attributes are not covered by the signature and can be changed or removed without affecting the signature.

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

Please refer to the SignatureAttribute type for a complete list of fields.

Config Method (Messageencryptor 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 (Messageencryptor 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 insensitive) 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;....

Encrypt Method (Messageencryptor Class)

Encrypts data.

Syntax

public void encrypt();

Remarks

This method encrypts the data provided via InputFile or InputStream in accordance with PKCS#7 standard.

If encrypted with an EncryptionCertificate a message of EnvelopedData subtype is created. The private key that corresponds to the certificate is needed to decrypt the data.

If encrypted with Key, a message of EncryptedData subtype is formed. The receiving party needs the same key as provided in Key to decrypt the message.

Error Event (Messageencryptor Class)

Information about errors during PKCS#7 message encryption.

Syntax

public class DefaultMessageencryptorEventListener implements MessageencryptorEventListener {
  ...
  public void error(MessageencryptorErrorEvent e) {}
  ...
}

public class MessageencryptorErrorEvent {
  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. For a list of valid error codes and their descriptions, please refer to the Messages section.

Notification Event (Messageencryptor Class)

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

Syntax

public class DefaultMessageencryptorEventListener implements MessageencryptorEventListener {
  ...
  public void notification(MessageencryptorNotificationEvent e) {}
  ...
}

public class MessageencryptorNotificationEvent {
  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 class. 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 the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

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.

SignatureAttribute Type

Represents an attribute of a digital PKCS#7/CMS signature.

Remarks

Attributes store auxiliary information about the signed message, the signature, or the owner. Each attribute is a OID=Value pair.

Common attributes are signing time, a content type, a policy identifier, and a signature timestamp.

Fields

Constructors

public SignatureAttribute();

Creates a new, empty, signature attribute.

Config Settings (Messageencryptor Class)

The class accepts one or more of the following configuration settings. Configuration 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.

MessageEncryptor Config Settings

Base Config Settings

Trappable Errors (Messageencryptor Class)

MessageEncryptor Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER)