SMIME Modules

Properties Config Settings

The SMIME transformer implements the S/MIME standard for encryption and decryption with public key cryptography and X.509 digital certificates.

Remarks

The SMIME module is used for encrypting, decrypting, signing, and verifying messages. The module uses the S/MIME V3 standard for encryption and decryption and can also generate and verify RSA digital signatures.

SMIME Encoder Module

The Encoder takes an unencrypted/unsigned data entity and generates an SMIME entity as output.

Encrypting

The Encoder will only encrypt incoming data if the EncryptData property is set to True. Encrypting requires that the RecipientCert property is set to a certificate containing the public key that should be used to encrypt the data. The EncryptingAlgorithm and UseOAEP properties can be specified for further control of encryption.

Signing

The Encoder will only sign the data if the SignData property is set to True. Signing requires that the Certificate property is set to a certificate containing the private key that should be used to sign the data. The SigningAlgorithm and UsePSS properties can be specified for further control of the signature.

Encryption and Signing Example

Drag and drop the SMIME Encoder into a flow. The message you want to encode should be passed by another connector.

The EncryptData property is enabled by default, so all you need to do to set up encryption is set the RecipientCert property to the certificate that will be used to decode the message.

To enable signing, set the SignData property to True, then set the SignerCert property to your own certificate. SMIME Decoder Module

The Decoder takes an encrypted/signed SMIME entity and will decrypt/verify the message and produce the original message.

Decrypting

The Decoder will only attempt to decrypt incoming data if the DecryptData property is set to True. Decryption requires that the Certificate property is set to a certificate containing the private key that can decrypt the data (the private key that is paired with the public key that was used to encrypt the data). The RequireOAEP property can be set to True to instruct the module to throw an error if the data was not encrypted with OAEP (Optimal Asymmetric Encryption Padding).

Verifying Signatures

The Decoder will only attempt to verify the signature of the incoming data if the VerifySignature property is set to True. Verification requires that the certificate used to sign the data was attached to the message, or that the SignerCert property is set to the signer's certificate. The RequirePSS property can be set to True to instruct the module to throw an error if the data was not signed with RSA-PSS (RSA Probabilistic Signature Scheme).

Decryption and Verification Example

Drag and drop the SMIME Decoder into a flow. The message you want to decode should be passed by another connector.

The DecryptData property is enabled by default, so all you need to do to set up decryption is set the Certificate property to the certificate you want to use to decode the message.

To enable signature verification, set the VerifySignature property to True, then set the SignerCert property to the certificate that was used to sign the message.

Encoder Property List

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


Certificate	The Certificate used to sign (Encoder) and decrypt (Decoder) messages.
DetachedSignature	Specifies whether to include a detached signature when signing a message.
EncryptData	Whether to encrypt the MIME data.
EncryptingAlgorithm	The algorithm to use for encryption.
IncludeCertificate	Specifies whether to include the signer's certificate with the signed message.
IncludeChain	Specifies whether to include the signer's certificate chain with the signed message.
IncludeHeaders	Specifies whether to include the message headers while encoding the message.
InputMessageHeadersString	Headers from the SMIME message.
LogFile	The file to write logging information to at runtime.
LogMode	What information gets logged during component execution.
LogType	How information gets logged during component execution.
Other	Defines a set of configuration settings to be used by the transformer.
RecipientCert	The certificate used to encrypt the MIME data.
RuntimeLicense	Specifies the component runtime license key.
SignData	Whether to sign the MIME data.
SigningAlgorithm	Textual description of the signature hash algorithm.
TempPath	The path to which temporary files are written at runtime.
UseOAEP	Whether to use OAEP when encrypting the MIME data.
UsePSS	Whether to use RSA-PSS when signing.

Decoder Property List

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


Certificate	The Certificate used to sign (Encoder) and decrypt (Decoder) messages.
DecryptData	Whether to decrypt the incoming SMIME data.
LogFile	The file to write logging information to at runtime.
LogMode	What information gets logged during component execution.
LogType	How information gets logged during component execution.
Other	Defines a set of configuration settings to be used by the transformer.
RequireOAEP	Whether an error should be thrown if OAEP was not used to encrypt the incoming message.
RequirePSS	Whether an error should be thrown if RSA-PSS was not used to encrypt the incoming message.
RuntimeLicense	Specifies the component runtime license key.
SignerCert	Contains the certificate of the message signer.
TempPath	The path to which temporary files are written at runtime.
VerifySignature	Whether to attempt to verify the signature on the SMIME data.

Config Settings

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


ApplyB64Encoding	Instructs the component to base64 encode the message when signing or encrypting.
GenerateSignatureTimestamp	Whether to generate timestamps in signatures.
IncludeHeaders	Tells the component whether to include the headers when encoding the message.
IncludeInternalHeaders	Tells the component whether or not to include the internal headers when encoding the message.
UseMimeHeaderFilename	Tells the component to set the Filename based on the MIME headers.

Certificate Property (SMIME Module)

The Certificate used to sign (Encoder) and decrypt (Decoder) messages.

Data Type

Certificate

Remarks

The connector uses this certificate to sign MIME data when S/MIME encoding. This property is also used to decrypt S/MIME entities in the Decoder, and it should be set to the certificate that holds the private key that is paired with the public key that was used to encrypt the data.

DecryptData Property (SMIME Module)

Whether to decrypt the incoming SMIME data.

Data Type

Boolean

Default Value

true

Remarks

If this property is true, the pipeline will attempt to decrypt the incoming message. If the data is not expected to be encrypted, this property should be set to false.

This property is not available in the Compressor/Encoder.

DetachedSignature Property (SMIME Module)

Specifies whether to include a detached signature when signing a message.

Data Type

Boolean

Default Value

false

Remarks

TBD

This property is not available in the Decompressor/Decoder.

EncryptData Property (SMIME Module)

Whether to encrypt the MIME data.

Data Type

Boolean

Default Value

true

Remarks

If false, the data will be encoded but not encrypted. The default is true.

This property is not available in the Decompressor/Decoder.

EncryptingAlgorithm Property (SMIME Module)

The algorithm to use for encryption.

Data Type

String

Default Value

"3DES"

Remarks

This property contains either the name of the algorithm (such as "RC2", "3DES", "DES", or "AES"), or an object identifier (OID) string representing the algorithm.

In the case of "RC2" ("RC2CBC") the key bit length is specified after the name. The following algorithm names are supported for RC2: "RC2CBC40", "RC2CBC64", and "RC2CBC128", with the default being 128 bit ("RC2CBC128").

In the case of "AES" ("AESCBC") the key bit length is specified after the name. The following algorithm names are supported for AES: "AESCBC128", "AESCBC192", and "AESCBC256", with the default being 128 bit ("AESCBC128").

When read, the value of the property always contains the OID of the algorithm, or an empty string if the algorithm is unknown.

This property is not available in the Decompressor/Decoder.

IncludeCertificate Property (SMIME Module)

Specifies whether to include the signer's certificate with the signed message.

Data Type

Boolean

Default Value

true

Remarks

If true, the certificate used to sign the message will be encoded and included in the message signature.

Including a certificate is the preferred method of building signed messages. If you do not include a certificate, the message recipient may not be able to verify the sender's signature.

This property is not available in the Decompressor/Decoder.

IncludeChain Property (SMIME Module)

Specifies whether to include the signer's certificate chain with the signed message.

Data Type

Boolean

Default Value

false

Remarks

If this property is set to True, the entire certificate's chain that was used to sign the message will be encoded and included in the message signature.

NOTE: To include the chain, the IncludeCertificate property must also be set to true.

This property is not available in the Decompressor/Decoder.

IncludeHeaders Property (SMIME Module)

Specifies whether to include the message headers while encoding the message.

Data Type

Boolean

Default Value

true

Remarks

If true (default), the connector will include the headers when signing and/or encrypting. If false, only the message will be encoded.

This property is not available in the Decompressor/Decoder.

InputMessageHeadersString Property (SMIME Module)

Headers from the SMIME message.

Data Type

String

Default Value

Remarks

TBD

This property is not available in the Decompressor/Decoder.

LogFile Property (SMIME Module)

The file to write logging information to at runtime.

Data Type

String

Default Value

Remarks

To write logging information to a file instead of using the connector's logging API, set this property to a valid file on disk and set the LogType property to "File".

LogMode Property (SMIME Module)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)

Default Value

Remarks

This property controls what information the connector logs. The possible values have the following affect on the connector's behavior:


Verbose	The connector will report all information regarding the transport.
Info	The connector will report all major operations, as well as all warnings and errors.
Warning	The connector will report any conditions that could result in unpredictable behavior as well as errors.
Error	The connector will report all errors that prevent normal operations from completing.
Fatal	The connector will report only serious errors that cause the connector to completely stop functioning.

LogType Property (SMIME Module)

How information gets logged during component execution.

Data Type

Enumeration

Possible Values

None (0)
Console (1)
File (2)

Default Value

Remarks

This property controls where the connector will log the information. The possible values have the following affect on the connector's behavior:


None	The connector will not report any logging information.
Console	The connector will report all logging information to the console.
File	The connector will report all logging information to a file. The desired file must be specified in the LogFile when this type has been selected.

Other Property (SMIME Module)

Defines a set of configuration settings to be used by the transformer.

Data Type

String

Default Value

Remarks

The module accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the module, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

RecipientCert Property (SMIME Module)

The certificate used to encrypt the MIME data.

Data Type

Certificate

Remarks

The connector uses the recipient's certificate to encrypt the MIME data so that it can be decrypted once it reaches the recipient. This property should be set to the appropriate certificate for encryption.

This property is not available in the Decompressor/Decoder.

RequireOAEP Property (SMIME Module)

Whether an error should be thrown if OAEP was not used to encrypt the incoming message.

Data Type

Boolean

Default Value

false

Remarks

By default, the connector will silently support decrypting messages regardless of whether they were encrypted with Optimal Asymmetric Encryption Padding (OAEP). If OAEP should be required, and thus an error should be thrown if OAEP is not detected, set this property to true.

This property is not available in the Compressor/Encoder.

RequirePSS Property (SMIME Module)

Whether an error should be thrown if RSA-PSS was not used to encrypt the incoming message.

Data Type

Boolean

Default Value

false

Remarks

By default, the connector will silently support decrypting and verifying messages regardless of whether they were signed with RSA Probabilistic Signature Scheme (RSA-PSS). If RSA-PSS should be required, and thus an error should be thrown if RSA-PSS is not detected, set this property to true.

This property is not available in the Compressor/Encoder.

RuntimeLicense Property (SMIME Module)

Specifies the component runtime license key.

Data Type

String

Default Value

Remarks

You can use the RuntimeLicense property to set the runtime key for the connector license.

SignData Property (SMIME Module)

Whether to sign the MIME data.

Data Type

Boolean

Default Value

false

Remarks

If true, the certificate held in the Certificate property will be used to sign the message.

This property is not available in the Decompressor/Decoder.

SignerCert Property (SMIME Module)

Contains the certificate of the message signer.

Data Type

Certificate

Remarks

This certificate is used to verify the signature on the incoming message. Setting this property is only necessary if the message does not have the signer's certificate attached to it.

This property is not available in the Compressor/Encoder.

SigningAlgorithm Property (SMIME Module)

Textual description of the signature hash algorithm.

Data Type

String

Default Value

"SHA256"

Remarks

This property specifies the hash algorithm used to prepare the message digest for signature.

This property must contain either the name of the algorithm (such as "MD5" or "SHA1"), or an object id (OID) string representing the hash algorithm. Possible values are:

sha1
md5
sha-256 (default)
sha-384
sha-512
sha-224

When read, the value of the property always contains the OID of the algorithm, or an empty string if the algorithm is unknown.

This property is not available in the Decompressor/Decoder.

TempPath Property (SMIME Module)

The path to which temporary files are written at runtime.

Data Type

String

Default Value

Remarks

If you are planning on working with binary files or large files, it is recommended that you set a valid path for this property. When set to a valid path this property tells the connector to use temp files when performing operations. If this is not set, all operations are done in memory and require that all input and output is in ASCII.

This property accepts the "%TEMP%" macro, which will be replaced with the default system temporary directory at runtime.

UseOAEP Property (SMIME Module)

Whether to use OAEP when encrypting the MIME data.

Data Type

Boolean

Default Value

false

Remarks

By default, the connector will use PKCS1 when encrypting the message. To use Optimal Asymmetric Encryption Padding (OAEP) instead, set this property to true.

This property is not available in the Decompressor/Decoder.

UsePSS Property (SMIME Module)

Whether to use RSA-PSS when signing.

Data Type

Boolean

Default Value

false

Remarks

To use RSA Probabilistic Signature Scheme (RSA-PSS) when signing, set this property to true. Note that the certificate used to sign does not itself need to be signed with RSA-PSS; any valid RSA certificate may be used with this setting.

This property is not available in the Decompressor/Decoder.

VerifySignature Property (SMIME Module)

Whether to attempt to verify the signature on the SMIME data.

Data Type

Boolean

Default Value

true

Remarks

If this property is true, the connector will throw an error if the incoming message is unsigned, or if the signature cannot be verified using the SignerCert.

This property is not available in the Compressor/Encoder.

Certificate Type

The digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Store
String
Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType field specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field in order to specify client certificates. If Store has a value, and Subject is set, a search for a certificate is initiated. Please refer to the Subject field for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.
SPC	Software publisher certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

StorePassword
String
Default Value: ""

If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.

StoreType
CertStoreTypes
Default Value: 0

The type of certificate store for this certificate.

The connector supports both public and private keys in a variety of formats. When the cstAuto value is used, the connector will automatically determine the type. This field can take one of the following values:


0 (cstUser - default)	For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note: This store type is not available in Java.
1 (cstMachine)	For Windows, this specifies that the certificate store is a machine store. Note: This store type is not available in Java.
2 (cstPFXFile)	The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)	The certificate store is the name of a Java Key Store (JKS) file containing certificates. Note: This store type is only available in Java.
5 (cstJKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format. Note: this store type is only available in Java.
6 (cstPEMKeyFile)	The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)	The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)	The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)	The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)	The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)	The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)	The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)	The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)	The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)	The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)	The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)	The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)	The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store). Note: This store type is only available in Java and .NET.
22 (cstBCFKSBlob)	The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format. Note: This store type is only available in Java and .NET.
23 (cstPKCS11)	The certificate is present on a physical security key accessible via a PKCS#11 interface. To use a security key, the necessary data must first be collected using the CERTMGR connector. The ListStoreCertificates method may be called after setting CertStoreType to `cstPKCS11`, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's `CertEncoded` parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key: `certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);`
99 (cstAuto)	The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

Subject
String
Default Value: ""

The subject of the certificate used for client authentication.

When this property is set, a search is performed in the current certificate store certificate with matching subject.

If an exact match is not found, the store is searched for subjects containing the value of the property.

When setting the property to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

Control.CertSubject = "Test"

If a match is not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

If a matching certificate is found, Subject is set to the full subject of the matching certificate.

Thumbprint
String (read-only)
Default Value: ""

The thumbprint of the certificate.

This field is used to specify the thumbprint of the certificate. When there are multiple certificates in the store that have the same subject, the thumbprint will be used to distinguish between them.

Config Settings (SMIME Module)

The connector 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 connector, access to these internal properties is provided through the Other property.

SMIME Config Settings

ApplyB64Encoding: Instructs the connector to base64 encode the message when signing or encrypting.

This setting allows you to control the base64 encoding of the resulting message. By default, this value is true, and the message will be base64 encoded when signing or encrypting.

GenerateSignatureTimestamp: Whether to generate timestamps in signatures.

For the Java and .NET Editions, if GenerateSignatureTimestamp is True, a timestamp will be generated and added to all signatures created by the connector.

The default value is True.

IncludeHeaders: Tells the connector whether to include the headers when encoding the message.

If true, the connector will include the headers when encoding. If false, only the message will be encoded.

The default value for IncludeHeaders is false.

IncludeInternalHeaders: Tells the connector whether or not to include the internal headers when encoding the message.

If true, the connector will include the internal message part headers. When set to false, only the message will be encoded.

The default value for IncludeInternalHeaders is true.

UseMimeHeaderFilename: Tells the connector to set the Filename based on the MIME headers.

If true, the connector will use the filename found in the MIME headers to set the SourceFileName. It first checks for the filename in "Content-Disposition", then the filename in "Content-Type", and then the name in "Content-Type".

The default value for UseMimeHeaderFilename is false.