EzCrypt Pipeline Component

Properties   Config Settings  

The EzCrypt Pipeline Component can be used to encrypt and decrypt data for regular transport.

Remarks

The EzCrypt Pipeline Component contains an encoder and a decoder that receive messages from the BizTalk Message Engine and perform cryptographic operations on the data. The encoder will produce an encrypted file that the decoder can then decrypt, making it possible to add secure storage to your business process.

Configuration

To use the EzCrypt Pipeline Component, first select an Algorithm. Only symmetric algorithms are supported in the EzCrypt Pipeline Component.

Next, set the KeyPassword to allow the pipeline component to generate the cryptographic Key and IV. Alternatively, you may set the Key and IV properties directly. Note that the same password may be used for the encoder and decoder to generate the same key and IV.

You can control the size of the key by setting the KeySize configuration setting. You can change how the cryptography is performed by setting the CipherMode and PaddingMode properties.

Encoder Property List


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

AlgorithmThe symmetric algorithm.
CipherModeThe cipher mode of operation.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe secret key for the symmetric algorithm.
KeyPasswordA password used by the pipeline component to generate the Key and IV .
OtherDefines a set of configuration settings to be used by the pipeline component.
PaddingModeThe padding mode.
RuntimeLicenseSpecifies the component runtime license key.
TransportLogTells the component where and how to report information about its operations.
UseHexWhether input or output is hex encoded.

Decoder Property List


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

AlgorithmThe symmetric algorithm.
CipherModeThe cipher mode of operation.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe secret key for the symmetric algorithm.
KeyPasswordA password used by the pipeline component to generate the Key and IV .
OtherDefines a set of configuration settings to be used by the pipeline component.
PaddingModeThe padding mode.
RuntimeLicenseSpecifies the component runtime license key.
TransportLogTells the component where and how to report information about its operations.
UseHexWhether input or output is hex encoded.

Config Settings


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

BlockSizeThe block size, in bits, of the cryptographic operation.
EncryptedDataEncodingThe encoding of the encrypted input or output data.
IncludeIVWhether to prepend the IV to the output data and read the IV from the input data.
KeyPasswordAlgorithmThe hash algorithm used to derive the Key and IV from the KeyPassword property.
KeyPasswordIterationsThe number of iterations performed when using KeyPassword to derive the Key and IV.
KeyPasswordSaltThe salt value used in conjunction with the KeyPassword to derive the Key and IV.
KeySizeThe size, in bits, of secret key for the symmetric algorithm.
PipelineOptionsOptions defining the validation and protection functionality of the pipeline component.
TeaAlgorithmThe TEA algorithm.

Algorithm Property (EzCrypt Pipeline component)

The symmetric algorithm.

Data Type

Enumeration

Possible Values

AES (0)
Blowfish (1)
CAST (2)
DES (3)
IDEA (4)
RC2 (5)
RC4 (6)
TEA (7)
Triple DES (8)
Twofish (9)
Rijndael (10)


Default Value

0

Remarks

This property specifies the symmetric algorithm to use. Possible values are:

  • 0 (AES - default)
  • 1 (Blowfish)
  • 2 (CAST)
  • 3 (DES)
  • 4 (IDEA)
  • 5 (RC2)
  • 6 (RC4)
  • 7 (TEA)
  • 8 (TripleDES)
  • 9 (Twofish)
  • 10 (Rijndael)
  • 11 (ChaCha)
  • 12 (XSalsa20)

CipherMode Property (EzCrypt Pipeline component)

The cipher mode of operation.

Data Type

Enumeration

Possible Values

CBC (0)
ECB (1)
OFB (2)
CFB (3)
CTS (4)


Default Value

0

Remarks

The cipher mode of operation.

Possible values are:

0 (cmCBC - default) The Cipher Block Chaining (CBC) is a mode of operation for a block cipher, one in which a sequence of bits is encrypted as a single unit or block with a cipher key applied to the entire block.
1 (cmECB) The Electronic Codebook (ECB) mode encrypts each block separately. Important: It is not recommend to use this model when encrypting more than one block because it may introduce security risks.
2 (cmOFB) The Output Feedback (n-bit, NOFB) mode makes a block cipher into a synchronous stream cipher. It has some similarities to CFB mode in that it permits encryption of differing block sizes, but has the key difference that the output of the encryption block function is the feedback (instead of the ciphertext).
3 (cmCFB) The Cipher Feedback (CFB) mode processes a small amount of incremental text into ciphertext, rather than processing a whole block at one time.
4 (cmCTS) The Cipher Text Stealing (CTS) mode handles any length of plain text and produces cipher text whose length matches the plain text length. This mode behaves like the CBC mode for all but the last two blocks of the plain text.
5 (cm8OFB) 8-bit Output Feedback (OFB) cipher mode.
7 (cm8CFB) 8-bit Cipher Feedback (CFB) cipher mode.

IV Property (EzCrypt Pipeline component)

The initialization vector used by the CipherMode to modify the ciphertext.

Data Type

String

Default Value

""

Remarks

The IV is an initialization vector used by the CipherMode to modify the ciphertext output by the pipeline component. This can add several degrees of security to the cipher.

Key Property (EzCrypt Pipeline component)

The secret key for the symmetric algorithm.

Data Type

String

Default Value

""

Remarks

This secret key is used both for encryption and decryption. The secret key should be known only to the sender and the receiver. The legal key size varies depending on the algorithm.

If this property is left empty it will be set to a random value by the adapter as necessary.

Legal Key and Block Sizes (in bits)

AES Rijndael CAST DES IDEA RC2 RC4 TripleDES Blowfish Twofish TEA
Minimum Key Size 128 128 112 64 128 112 112 128 112 128 128
Maximum Key Size 256 256 128 64 128 128 2048 192 448 256 128
Key Size Step 64 64 8 0 0 8 8 64 1 8 0
Block Size 128 128/192/256 64 64 64 64 N/A 64 64 128 64*

Note: When using TEA if Algorithm is set to XXTEA valid block sizes are 64 + n * 32. Where n is any positive integer.

The default KeySize is the Maximum Key Size.

KeyPassword Property (EzCrypt Pipeline component)

A password used by the pipeline component to generate the Key and IV .

Data Type

Password

Default Value

""

Remarks

The pipeline component can use the KeyPassword to fill in the values of Key and IV using the PKCS5 password digest algorithm. The size of the Key generated is dependent on the value of KeySize.

Other Property (EzCrypt Pipeline component)

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

Data Type

String

Default Value

""

Remarks

The pipeline component 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 pipeline component, 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

PaddingMode Property (EzCrypt Pipeline component)

The padding mode.

Data Type

Enumeration

Possible Values

PKCS7 (0)
Zeros (1)
None (2)
ANSIX923 (3)
ISO10126 (4)


Default Value

0

Remarks

PaddingMode is used to pad the final input block to guarantee that it is the correct size required for the selected CipherMode. Each mode pads the data differently. Possible values are:

0 (pmPKCS7 - default) The data is padded with a series of bytes that are each equal to the number of bytes used. For instance, in the example below the data must be padded with 3 additional bytes, so each byte value will be 3.

Raw Data: AA AA AA AA AA PKCS7 Padded Data: AA AA AA AA AA 03 03 03
1 (pmZeros) The data is padded with null bytes.
2 (pmNone) No padding will be performed.
3 (pmANSIX923) The ANSIX923 padding string consists of a sequence of bytes filled with zeros before the length. For instance, in the example below the data must be padded with 3 additional bytes, so last byte value will be 3.

Raw Data: AA AA AA AA AA ANSIX923 padding Data: AA AA AA AA AA 00 00 03
4 (pmISO10126) The ISO10126 padding string consists of random data before the length. For instance, in the example below the data must be padded with 3 additional bytes, so last byte value will be 3.

Raw Data: AA AA AA AA AA ISO10126 padding Data: AA AA AA AA AA F8 EF 03

When decrypting the PaddingMode must match the value used when the data was encrypted.

Note: When using a value of 2 (pmNone), unless the length of input is an exact multiple of the cipher's input BlockSize, the final block of plaintext may be lost.

RuntimeLicense Property (EzCrypt Pipeline component)

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 adapter license.

This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.

TransportLog Property (EzCrypt Pipeline component)

Tells the component where and how to report information about its operations.

Data Type

Log

Remarks

This is a Log type property which contains fields describing how and where the adapter will record information about its execution.

This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.

UseHex Property (EzCrypt Pipeline component)

Whether input or output is hex encoded.

Data Type

Boolean

Default Value

false

Remarks

This property specifies whether the encrypted data is hex encoded.

If set to True, when encrypting the adapter will perform the encryption as normal and then hex encode the output.

If set to True, when decrypting the adapter will expect the input to hold hex encoded data. The adapter will then hex decode the data and perform decryption as normal.

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:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.
SPCSoftware 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 adapter supports both public and private keys in a variety of formats. When the cstAuto value is used the adapter 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 (PKCS12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) 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 PKCS7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS7 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 PKCS11 interface.

To use a security key the necessary data must first be collected using the CERTMGR adapter. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS11 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.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Certificate();

Creates a Certificate instance whose properties can be set.

public Certificate(string certificateFile);

Opens CertificateFile and reads out the contents as an X509 public key.

public Certificate(byte[] certificateData);

Parses CertificateData as an X509 public key.

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Firewall Type

The firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall such as the firewall Host and the FirewallType.

Fields

AutoDetect
Boolean

Default Value: False

Tells the adapter whether or not to automatically detect and use firewall system settings, if available.

FirewallType
FirewallTypes

Default Value: 0

Determines the type of firewall to connect through. The applicable values are the following:

fwNone (0)No firewall (default setting).
fwTunnel (1)Connect through a tunneling proxy. Port is set to 80.
fwSOCKS4 (2)Connect through a SOCKS4 Proxy. Port is set to 1080.
fwSOCKS5 (3)Connect through a SOCKS5 Proxy. Port is set to 1080.

Host
String

Default Value: ""

Name or IP address of firewall (optional). If a Host is given, requested connections will be authenticated through the specified firewall when connecting.

If the Host field is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the Host field is set to the corresponding address. If the search is not successful, an error is returned.

Password
String

Default Value: ""

A password if authentication is to be used when connecting through the firewall. If Host is specified, the User and Password fields are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

Port
Integer

Default Value: 0

The TCP port for the firewall Host. See the description of the Host field for details.

Note that the Port is set automatically when FirewallType is set to a valid value. See the description of the FirewallType field for details.

User
String

Default Value: ""

A user name if authentication is to be used connecting through a firewall. If the Host is specified, the User and Password fields are used to connect and authenticate to the given Firewall. If the authentication fails, a trappable error is fired.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Firewall();

Log Type

A log where the component will record information about its operations.

Remarks

This describes how and where the adapter will record information describing its execution.

Fields

Location
String

Default Value: "Application"

This field describes the location where the logging information is to be written.

If the EventLog LogType has been chosen, this field must contain the name of the Event Log to which the information should be written. The default value for this field is "Application". If a value other than "Application" is set the computer must be restarted for the change to take effect. Note that the same event log must be used for all send ports and receive locations that use the same adapter.

If the File LogType has been chosen, this field must contain the location of the file to write logging information to on the file system.

The adapter also supports logging to files based on the current date and time. This allows for log files to be organized by days, months, or other intervals as specified. When specifying a log filename include a valid .NET date and time format string within the < and > characters. For instance C:\logs\sftp_<yyyyMMdd>.log or C:\logs\as2_<yyyyMMdd>T<hhmm>.log.

LogMode
LogModes

Default Value: 3

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

VerboseThe adapter will report all information regarding the transport.
Info The adapter will report all major operations, as well as all warnings and errors.
WarningThe adapter will report any conditions that could result in unpredictable behavior as well as errors.
ErrorThe adapter will report all errors that prevent normal operations from completing.
FatalThe adapter will report only serious errors that cause the adapter to completely stop functioning.

LogType
LogTypes

Default Value: 1

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

NoneThe adapter will not report any logging information.
EventLogThe adapter will report all logging information to the event log. The specific event log must be defined in the Location field when this type is selected.
FileThe adapter will report all logging information to a file. The desired file must be specified in the Location field when this type has been selected.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Log();
public Log(LogTypes logType, string location, LogModes logMode);

OAuthAuthorizationParam Type

This type holds details of the OAuth authorization.

Remarks

This type holds details of the OAuth authorization.

Fields

AuthorizationScopes
String

Default Value: ""

A space separated list of scopes as defined by the authorization server.

AuthorizationString
String

Default Value: ""

The OAuth Authorization string. This field holds the current OAuth authorization string. This is retrieved during the OAuth authorization process and is used to authenticate the request. This is a string like:

Bearer ya29.AHES6ZSZEJzATdZYjeihDn5W-VrXSsxEZu5p0pclxGdKKQ

CacheLocation
String

Default Value: ""

The location on disk of the OAuth Cache File.

This field specifies the location on disk of the OAuth cache file. This file holds OAuth credentials that may be automatically used during runtime and by other ports using the same provider. The adapter uses the data within the cache file to automatically refresh expired tokens at runtime. Do not alter the contents of the file directly.

One file for each provider is used by default. For instance for Box the value is: %APPDATA%\nsoftware\CloudStorage BizTalk Adapter\BoxOAuthCache.txt

This value may be specified manually as well.

CallbackURL
String

Default Value: ""

The Callback URL used during OAuth authorization.

This field specifies the local URL to which the browser is redirected when initially performing authorization. When initially establishing Authorization set this value to the redirect URI that is registered for your application with the service provider. For instance "http://localhost:7777".

The adapter will parse this URL and start a small embedded web server on the specified port to receive the OAuth response from the provider during OAuth authorization.

This value is required to perform OAuth authorization.

ClientId
String

Default Value: ""

The id of the client assigned when registering the application.

This field holds the id of the client that was assigned when initially registering the application.

This value is required to perform OAuth authorization.

ClientSecret
String

Default Value: ""

The secret of the client assigned when registering the application.

This field holds the secret of the client that was assigned when initially registering the application.

This value is required to perform OAuth authorization.

ExpiresIn
Integer

Default Value: 0

The expiration time of the current OAuth authorization string.

This value is populated after OAuth authorization and holds the expiration time of the OAuth access token as reported by the service provider. This is used at runtime to calculate whether the token should be refreshed before attempting an operation. If the token is expired the adapter will automatically refresh the token. If the token is not expired the adapter will use the current token.

This value should not be set manually.

Note: Not all providers provide this value. For instance Dropbox access tokens never expire.

RefreshToken
String

Default Value: ""

The refresh token received from or sent to the authorization server.

This field holds the refresh token received during the initial OAuth authorization. It is used by the adapter to automatically request a new AuthorizationString when the current value expires.

ServerAuthURL
String

Default Value: ""

The URL of the authorization server.

ServerTokenURL
String

Default Value: ""

The URL of the token server.

ServiceProvider
String

Default Value: ""

The service provider to authenticate with.

This field defines the service provider. This is used when performing OAuth authorization. OAuth authorization is only applicable to some providers. If the provider does not support OAuth a warning will be displayed. Possible values when using the Cloud Storage adapter are:

  • Amazon S3
  • Azure Blob
  • Azure File
  • Backblaze B2
  • Box.com
  • Digital Ocean Spaces
  • Dropbox
  • Google Cloud Storage
  • Google Drive
  • Hadoop DFS
  • IBM Cloud Object Storage
  • Linode Object Storage
  • Microsoft OneDrive
  • Wasabi
Possible values when using the Email adapter are:

  • Gmail
  • Other

TimeStamp
String

Default Value: "0"

The timestamp of the OAuth authorization string.

This field holds the timestamp of when the AuthorizationString was retrieved. This is used in conjunction with ExpiresIn to calculate if refreshing the token is required. For more details see ExpiresIn.

This value should not be set manually.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public OAuthAuthorizationParam();

Config Settings (EzCrypt Pipeline component)

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

EzCrypt Config Settings

BlockSize:   The block size, in bits, of the cryptographic operation.

The block size is a basic data unit in the operation of encrypt or decrypt. Messages longer than the block size are seen as successive blocks. If the message is shorter than the block size, the message will be padded with extra bits to reach the block size according to PaddingMode. Different symmetric algorithm has different valid block sizes.

The following algorithms have a fixed block size: AES, CAST, DES, IDEA, RC2, TripleDES, Blowfish, and Twofish.

EncryptedDataEncoding:   The encoding of the encrypted input or output data.

This configuration setting specifies how the encrypted data is encoded (if at all).

When Encrypt is called the adapter will perform the encryption as normal and then encode the output as specified here. OutputMessage or OutputFile will hold the encoded data.

When Decrypt is called the adapter will expect InputMessage or InputFile to hold the encoded data as specified here. The adapter will then decode the data and perform decryption as normal.

Possible values are:

  • 0 (none - default)
  • 1 (Base64)
  • 2 (Hex)
  • 3 (Base64URL)

IncludeIV:   Whether to prepend the IV to the output data and read the IV from the input data.

If this config is true, the IV will be automatically prepended to the output data when encrypting. When decyrpting and this setting is True, the IV is automatically extracted form the ciphertext. The default value is False.

KeyPasswordAlgorithm:   The hash algorithm used to derive the Key and IV from the KeyPassword property.

This configuration setting specifies which hash algorithm will be used when deriving the Key and IV from KeyPassword. The default value is "MD5". Possible values are:

  • "SHA1"
  • "MD2"
  • "MD5" (default)
  • "HMAC-SHA1"
  • "HMAC-SHA224"
  • "HMAC-SHA256"
  • "HMAC-SHA384"
  • "HMAC-SHA512"
  • "HMAC-MD5"
  • "HMAC-RIPEMD160"

When using any HMAC algorithm the PBKDF#2 method from RFC 2898 is used. Any other algorithm uses PBKDF#1 from the same RFC.

KeyPasswordIterations:   The number of iterations performed when using KeyPassword to derive the Key and IV.

This configuration setting specifies the number of iterations performed when using KeyPassword to calculate values for Key and IV. When using PBKDF#2 the default number of iterations is 10,000. When using PBKDF#1 the default number is 10.

KeyPasswordSalt:   The salt value used in conjunction with the KeyPassword to derive the Key and IV.

This configuration setting specifies the hex encoded salt value to be used along with the KeyPassword when calculating values for Key and IV.

KeySize:   The size, in bits, of secret key for the symmetric algorithm.

The legal key sizes vary depending on the algorithm. The KeySize and BlockSize configuration settings may be set to specify the key and block size (in bits).

This setting is only applicable when KeyPassword is specified.

Note that when using the EzCrypt adapter, KeySize should be set after setting the Algorithm property.

PipelineOptions:   Options defining the validation and protection functionality of the pipeline component.

By default the pipeline will protect (encrypt) sensitive fields such as passwords, and will validate required properties are set. In some cases it may be desirable to change this behavior. This setting may be used to disable the protection, validation, or both. Possible values are:

0 (default) Both Protection and Validation are enabled
1 Protection is disabled. Validation is enabled.
2 Validation is disabled. Protection is enabled.
3 Validation and Protection are disabled.
TeaAlgorithm:   The TEA algorithm.

This property specifies the TEA algorithm to use. It is recommended to use the XXTEA (Corrected Block TEA) algorithm for security reasons. Possible values are:

0 (taXXTEA - default) Correct Block TEA
1 (taXTEA) eXtended TEA
2 (taTEA) TEA (Tiny Encryption Algorithm)

Supported Macros

The adapter also supports the following Macros. These values are not case sensitive and would be supplied to a property in the form %MacroName%.

TempThis is resolved to the full path to the system's temporary directory. MessageIDGlobally unique identifier (GUID) of the message in BizTalk Server. SourceFileNameThe original file name. This includes the extension and excludes the file path, for example, Sample.xml SourceFileNameNoExtThe original file name without the extension or file path, for example, Sample RemoteFileNameThe name of the file as it was uploaded to the remote server. This includes the extension and excludes the file path, for example, Sample.xml. Valid only for AS3, FTP, and SFTP Send Adapters. DestinationPartyName of the destination party. DestinationPartyQualifierQualifier of the destination party. SourcePartyName of the source party. SourcePartyQualifierQualifier of the source party. DateTime:CustomFormatThis special value allows you to specify your own custom time format. For instance DateTime:yyyy would be resolved to the 4 digit year. DateThe date format yyyy-MM-dd. DateTimeThe date format yyyy-MM-ddThhmmss. TimeThe date format hhmmss. DateTime_BTS2000The date format yyyyMMddhhmmssf. DateTime.TZThe date format yyyy-MM-ddThhmmsszzz. Time.TZThe date format hhmmsszzz. Property#<Schema>#<Name>This special value allows you to include a property from the incoming message. For instance "PROPERTY#http://schemas.microsoft.com/BizTalk/2003/system-properties#ReceivePortName" would resolve to the ReceivePortName property of the message.