AES Pipeline Component

Properties   Config Settings  

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

Remarks

The AES 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

Since AES is a symmetric-key algorithm, the settings for the Encode operations and Decode operations are the exact same.

First set the KeySize to determine the strength of the cipher to be used. 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 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.

AdditionalAuthDataAdditional authentication data (AAD) used in GCM mode.
CipherModeControls how the pipeline component uses the IV to modify the cipher algorithm.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe raw key used by the cipher.
KeyPasswordA password used by the pipeline component to generate the Key and IV .
KeySizeThe size of the Key .
OtherDefines a set of configuration settings to be used by the pipeline component.
PaddingModeUsed by the cipher to pad the last block of input text.
RuntimeLicenseSpecifies the component runtime license key.
TransportLogTells the component where and how to report information about its operations.

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.

AdditionalAuthDataAdditional authentication data (AAD) used in GCM mode.
CipherModeControls how the pipeline component uses the IV to modify the cipher algorithm.
IVThe initialization vector used by the CipherMode to modify the ciphertext.
KeyThe raw key used by the cipher.
KeyPasswordA password used by the pipeline component to generate the Key and IV .
KeySizeThe size of the Key .
OtherDefines a set of configuration settings to be used by the pipeline component.
PaddingModeUsed by the cipher to pad the last block of input text.
RuntimeLicenseSpecifies the component runtime license key.
TransportLogTells the component where and how to report information about its operations.

Config Settings


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

AuthTagLengthThe authentication tag length used in GCM mode.
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.
PipelineOptionsOptions defining the validation and protection functionality of the pipeline component.

AdditionalAuthData Property (AES Pipeline component)

Additional authentication data (AAD) used in GCM mode.

Data Type

String

Default Value

""

Remarks

This setting optionally specifies additional authentication data. The data specified must be hex encoded. This is only applicable when CipherMode is set to 6 (cmGCM). This may be set prior to encryption or decryption.

Note that AAD data is authenticated but not encrypted, so it is not included in the output message.

CipherMode Property (AES Pipeline component)

Controls how the pipeline component uses the IV to modify the cipher algorithm.

Data Type

Enumeration

Possible Values

CBC (1)
ECB (2)
OFB (3)
CFB (4)
CTS (5)
8OFB (6)
8CFB (7)
GCM (8)


Default Value

1

Remarks

CipherMode can be used to allow the pipeline component to use an initialization vector (IV) to manipulate the output from the cipher. This can add several degrees of security to the basic cipher algorithm.

CBC - Cipher Block ChainingEach block of data output by the cipher is XOR'd with the next block of plaintext to change the input. The IV is used as the first block.
ECB - Electronic CodebookThis is the basic cipher algorithm. The value of the IV will be ignored.
OFB - Output FeedbackThe output of each cipher call is XOR'd with the plaintext to produce the ciphertext and the same output is used as the input for the next cipher call. The IV is used as the first input block.
CFB - Cipher FeedbackEach block of ciphertext is encrypted again and XOR'd with the plaintext to produce the next block of ciphertext. The IV is used as the first input block.
CTS - Cipher Text StealingHandles 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.
8OFB - 8-bit Output FeedbackOFB cipher in 8-bit mode.
8CFB - 8-Bit Cipher FeedbackCFB cipher in 8-bit mode.
GCM - Galois/Counter ModeEach input block is counted, and the current value of the counter is sent through the block cipher. The output of the block cipher is XOR'd with the corresponding plaintext block to form the ciphertext.

Note: the default cipher mode is CBC as it provides a very strong layer of added security for a minimum of extra CPU power.

IV Property (AES 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 (AES Pipeline component)

The raw key used by the cipher.

Data Type

String

Default Value

""

Remarks

The Key is a master key used to create the set of encryption and decryption keys that can be used by the cipher. Note that the same key must be used for the encoder and decoder in order to correctly decrypt the encrypted data.

KeyPassword Property (AES 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.

KeySize Property (AES Pipeline component)

The size of the Key .

Data Type

Enumeration

Possible Values

128 (128)
196 (192)
256 (256)


Default Value

256

Remarks

KeySize can be used to change the size of the key generated when the KeyPassword is set. If Key is set directly, KeySize will reflect the size of that key. The size of the key also determines the strength of the cipher algorithm:

  • weak - 128 bits
  • medium - 192 bits
  • strong - 256 bits

Note: the default key size is 256 to ensure the maximum cipher strength.

Other Property (AES 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 (AES Pipeline component)

Used by the cipher to pad the last block of input text.

Data Type

Enumeration

Possible Values

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


Default Value

2

Remarks

PaddingMode is used by the cipher to pad the final input block to guarantee that it is the correct size required for the cipher's input. Each mode pads the data differently:

NoneNo padding will be performed.
PKCS7The data is padded with by a series of bytes that are each equal to the number of bytes used (eg: 03 03 03)
ZerosThe data is padded by several null bytes (eg: 00 00 00).
ANSIX923The data is padded by a sequence of null bytes followed by the number of bytes in the padding.
ISO10126The data is padded by a sequence of random bytes followed by the number of bytes in the padding.

Note: unless the length of input is an exact multiple of the cipher's input block size (16 bytes for AES), the final block of plaintext may be lost if None is used. In order to avoid this, the default PaddingMode is PKCS7.

RuntimeLicense Property (AES 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 (AES 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.

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

Config Settings (AES 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.

AES Config Settings

AuthTagLength:   The authentication tag length used in GCM mode.

This setting is only applicable when CipherMode is set to 8 (cmGCM). The default value is 128. Valid values are

  • 96
  • 104
  • 112
  • 120
  • 128 (default)
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.

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.

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.