MessageEncryptor Module

Properties   Methods   Events   Config Settings   Errors  

The MessageEncryptor module 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 module with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

BitsInKey Property (MessageEncryptor Module)

The length of the encryption key.

Syntax

• Swift
• Objective-C

public var bitsInKey: Int32 {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=bitsInKey,setter=setBitsInKey:) int bitsInKey;

- (int)bitsInKey;
- (void)setBitsInKey :(int)newBitsInKey;

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 Module)

The symmetric key algorithm to use for encryption.

Syntax

• Swift
• Objective-C

public var encryptionAlgorithm: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=encryptionAlgorithm,setter=setEncryptionAlgorithm:) NSString* encryptionAlgorithm;

- (NSString*)encryptionAlgorithm;
- (void)setEncryptionAlgorithm :(NSString*)newEncryptionAlgorithm;

Default Value

"AES128"

Remarks

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

EncryptionCertificate Property (MessageEncryptor Module)

The certificate to use for encryption.

Syntax

• Swift
• Objective-C

public var encryptionCertificate: Certificate {
  get {...}
  set {...}
}

@property (nonatomic,readonly,assign,getter=encryptionCertBytes) NSData* encryptionCertBytes;

- (NSData*)encryptionCertBytes;

@property (nonatomic,readwrite,assign,getter=encryptionCertHandle,setter=setEncryptionCertHandle:) long long encryptionCertHandle;

- (long long)encryptionCertHandle;
- (void)setEncryptionCertHandle :(long long)newEncryptionCertHandle;

 

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.

EncryptionType Property (MessageEncryptor Module)

Specifies the kind of encrypted message to create.

Syntax

• Swift
• Objective-C

public var encryptionType: MessageencryptorEncryptionTypes {
  get {...}
  set {...}
}

public enum MessageencryptorEncryptionTypes: Int32 {
  case metUnknown = 0
  case metCertEncrypted = 1
  case metKeyEncrypted = 2
  case metCertEncryptedAndAuthenticated = 3
}

@property (nonatomic,readwrite,assign,getter=encryptionType,setter=setEncryptionType:) int encryptionType;

- (int)encryptionType;
- (void)setEncryptionType :(int)newEncryptionType;

Default Value

1

Remarks

Possible values:

FIPSMode Property (MessageEncryptor Module)

Reserved.

Syntax

• Swift
• Objective-C

public var fipsMode: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=FIPSMode,setter=setFIPSMode:) BOOL FIPSMode;

- (BOOL)FIPSMode;
- (void)setFIPSMode :(BOOL)newFIPSMode;

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (MessageEncryptor Module)

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

Syntax

• Swift
• Objective-C

public var inputBytes: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputBytes,setter=setInputBytes:) NSData* inputBytes;

- (NSData*)inputBytes;
- (void)setInputBytes :(NSData*)newInputBytes;

Remarks

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

InputFile Property (MessageEncryptor Module)

A path to the source file.

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

Default Value

""

Remarks

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

Key Property (MessageEncryptor Module)

The symmetric key to use for encryption.

Syntax

• Swift
• Objective-C

public var key: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=key,setter=setKey:) NSData* key;

- (NSData*)key;
- (void)setKey :(NSData*)newKey;

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.

OutputBytes Property (MessageEncryptor Module)

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

Syntax

• Swift
• Objective-C

public var outputBytes: Data {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputBytes) NSData* outputBytes;

- (NSData*)outputBytes;

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.

OutputFile Property (MessageEncryptor Module)

A path to the output file.

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

Default Value

""

Remarks

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

SignedAttributes Property (MessageEncryptor Module)

Custom signature attributes to be covered by the electronic signature.

Syntax

• Swift
• Objective-C

public var signedAttributes: Array<SignatureAttribute> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=signedAttributeCount,setter=setSignedAttributeCount:) int signedAttributeCount;

- (int)signedAttributeCount;
- (void)setSignedAttributeCount :(int)newSignedAttributeCount;

- (NSString*)signedAttributeOID:(int)signedAttributeIndex;
- (void)setSignedAttributeOID:(int)signedAttributeIndex :(NSString*)newSignedAttributeOID;

- (NSData*)signedAttributeValue:(int)signedAttributeIndex;
- (void)setSignedAttributeValue:(int)signedAttributeIndex :(NSData*)newSignedAttributeValue;

Remarks

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

UnsignedAttributes Property (MessageEncryptor Module)

Custom unsigned attributes to be included in the electronic signature.

Syntax

• Swift
• Objective-C

public var unsignedAttributes: Array<SignatureAttribute> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=unsignedAttributeCount,setter=setUnsignedAttributeCount:) int unsignedAttributeCount;

- (int)unsignedAttributeCount;
- (void)setUnsignedAttributeCount :(int)newUnsignedAttributeCount;

- (NSString*)unsignedAttributeOID:(int)unsignedAttributeIndex;
- (void)setUnsignedAttributeOID:(int)unsignedAttributeIndex :(NSString*)newUnsignedAttributeOID;

- (NSData*)unsignedAttributeValue:(int)unsignedAttributeIndex;
- (void)setUnsignedAttributeValue:(int)unsignedAttributeIndex :(NSData*)newUnsignedAttributeValue;

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.

Config Method (MessageEncryptor Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)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 Module)

Performs an additional action.

Syntax

• Swift
• Objective-C

public func doAction(actionID: String, actionParams: String) throws -> String

- (NSString*)doAction:(NSString*)actionID :(NSString*)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 Module)

Encrypts data.

Syntax

• Swift
• Objective-C

public func encrypt() throws -> Void

- (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 Module)

Information about errors during PKCS#7 message encryption.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)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 Module)

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

Syntax

• Swift
• Objective-C

func onNotification(eventID: String, eventParam: String)

- (void)onNotification:(NSString*)eventID :(NSString*)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 init(stream: )

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

public init()

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 = pair.

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

Fields

Constructors

public init()

Creates a new, empty, signature attribute.

Config Settings (MessageEncryptor Module)

MessageEncryptor Config Settings

Base Config Settings

Trappable Errors (MessageEncryptor Module)

MessageEncryptor Errors