Zip Pipeline Component

The Zip pipeline component implements a PKZip-compatible Zip compressor and decompressor.

Remarks

The Zip pipeline component is used for compressing and decompressing messages. The pipeline component uses the Deflate algorithm specified in RFC 1951 for compression, and produces and reads output compatible with PKZip, WinZip, etc.

Zip Assembler Pipeline Component

The Assembler takes a group of messages as input which contains raw data, and generates a Zip archive message as output.

Compression strength is regulated by the CompressionLevel property. You may also control encryption behavior by setting the Password and EncryptionAlgorithm properties on this pipeline component.

Zip Disassembler Pipeline Component

The Disassembler takes a zipped message as input, and generates a group of unzipped messages as output.

The Password property must be set in order to extract messages which have been encrypted. You may also use the ExcludedFiles property to regulate which messages are to be extracted from the archive.

Please refer to the section on adapter configuration for a description of how to configure receive locations and send ports for this adapter.

Assembler Property List

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


ArchiveFileName	The name of the zip archive.
CompressionLevel	The compression level to use.
EncryptionAlgorithm	The algorithm used to encrypt a message when written to the archive.
ExcludedFiles	A list of messages to exclude.
FileModifiedTime	The modified time of the compressed file.
Other	Defines a set of configuration settings to be used by the pipeline component.
Password	A password for the zip message.
RuntimeLicense	Specifies the component runtime license key.
TempPath	A temporary directory where uncompressed and compressed data can be stored.
TransportLog	Tells the component where and how to report information about its operations.
ZipComment	The comment for the entire zip message.

Disassembler Property List

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


ExcludedFiles	A list of messages to exclude.
FileMask	Specifies which files the component should include when extracting.
Other	Defines a set of configuration settings to be used by the pipeline component.
Password	A password for the zip message.
RuntimeLicense	Specifies the component runtime license key.
TempPath	A temporary directory where uncompressed and compressed data can be stored.
TransportLog	Tells 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.


Append	Specifies whether to append files.
ArchiveFile	The location of the archive file on disk.
CompressionMethod	Used to set the method of compression.
PipelineOptions	Options defining the validation and protection functionality of the pipeline component.
PlainPassword	Allows you to specify a password stored in plaintext.
PreserveModifiedTime	Whether or not to preserve the original modified time on extracted files.
SSOPassword	Specifies the key name in the SSO configuration that holds the password value.

ArchiveFileName Property (Zip Pipeline component)

The name of the zip archive.

Data Type

String

Default Value

Remarks

If specified this determines the name of the archive created by the adapter.

This property is not available in the Disassembler/Decoder.

CompressionLevel Property (Zip Pipeline component)

The compression level to use.

Data Type

Integer

Default Value

Remarks

This property specifies the level of compression to be used, between 0 and 6. Higher values will cause the pipeline component to compress better; lower values will cause the pipeline component to compress faster. A value of 0 will store the message without compression.

This property is not available in the Disassembler/Decoder.

EncryptionAlgorithm Property (Zip Pipeline component)

The algorithm used to encrypt a message when written to the archive.

Data Type

Enumeration

Possible Values

Default (0)
AESWeak (1)
AESStrong (2)
AESMaximum (3)

Default Value

Remarks

The algorithm used to encrypt each message written to the archive.

Note that the Password property must be set in order for the pipeline component to encrypt messages. By default the pipeline component will use standard zip encryption if Password is set, and will not encrypt data otherwise.

The pipeline component supports the use of AES, the Advanced Encryption Standard, as well as standard Zip encryption. The default encryption algorithm is the algorithm introduced in version 2.0 of the Zip specification, and is compatible with virtually all other zip utilities. However, this algorithm is considered weak and should not be used to protect sensitive data.

AES is a U.S. government standard cleared to protect even the most sensitive data. The file format used to create AES-encrypted files is designed to be compatible with WinZip 9.0. AES-encrypted files created by the pipeline component may or may not be compatible with other Zip utilities.

The pipeline component supports the use of AES with key lengths of 128, 192, or 256 bits. Note that even with the weakest (128-bit) keys, AES is much more secure than standard Zip encryption.

If you use strong or maximum AES encryption, the pipeline component will generate a unique salt value and cryptographic key for each message encrypted. If you use weak encryption the adapter will use the same salt for each message in the archive. If you are encrypting a large number of messages, this will have a substantial effect on performance.

If using AES encryption it is important to choose a good Password. For 128-bit keys it is recommended that your password be 32 characters long, and for 256-bit keys, 64 characters.

Important: Note that AES encryption only encrypts the contents of encrypted messages within the Zip archive; it does not prevent an attacker from reading the names of files in the archive, or from adding or deleting files to or from the archive. To prevent this consider first storing your messages in an unencrypted zip message, and then storing this zipped message in another, AES-encrypted zip message.

Property values:


eaDefault	0
eaAESWeak	1
eaAESStrong	2
etAESMaximum	3

This property is not available in the Disassembler/Decoder.

ExcludedFiles Property (Zip Pipeline component)

A list of messages to exclude.

Data Type

String

Default Value

Remarks

This property specifies messages that should be excluded when compressing or extracting a message. When either compression or extraction occurs, each message will be compared to ExcludedFiles, and each message that matches will be excluded.

This property may be set to one or more message names. These message names may be specified with or without a path, and with or without wildcards. If a path is specified, messages in the indicated extraction directory will be excluded. If no path is specified but wildcards are, matching messages in all directories will be excluded. If a single message name without a path is specified, it must correspond exactly to the appropriate value of a valid message name.

Directories should end with a slash ("/" or "\", as appropriate.) If a directory is specified, all files and subdirectories in the specified directory will be excluded during extraction.

A pipe character ("|") should be used to separate multiple message or directory names.

If the property is set to the empty string, no messages will be excluded.

FileMask Property (Zip Pipeline component)

Specifies which files the component should include when extracting.

Data Type

String

Default Value

"*"

Remarks

FileMask may be used to specify which files will be extracted from the zip archive during decompression. All other files will be discarded.

The value should be a pipe ("|") -delimited sequence of one or more filenames. The filenames should be specified with paths if necessary.

Filenames may include the wildcards '?', '*', and '< .. >'. '?' will match any single character, and '*' will match an arbitrary sequence of characters. '< .. >' may be used to match any of the characters inside, or a range, such as '<a-z>'.

During extraction, FileMask may be set to one or more filenames or directory names. Files may be specified with or without a path, and with or without wildcards.

The ExcludedFiles property may be used to limit the files to be extracted.

This property is not available in the Assembler/Encoder.

FileModifiedTime Property (Zip Pipeline component)

The modified time of the compressed file.

Data Type

String

Default Value

Remarks

This property optionally specifies the modified time of the compressed file. The format may be any standard .NET DateTime format. For instance: "2010-08-13T14:33:11".

This property is not available in the Disassembler/Decoder.

Other Property (Zip 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

Password Property (Zip Pipeline component)

A password for the zip message.

Data Type

Password

Default Value

Remarks

This property specifies the case-sensitive password used to encrypt or decrypt the archive message. If set to an empty string, no password is used.

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

TempPath Property (Zip Pipeline component)

A temporary directory where uncompressed and compressed data can be stored.

Data Type

String

Default Value

Remarks

This property indicates a temporary directory where the pipeline component can store any data before the pipeline component processes it. If TempPath is empty, the pipeline component will receive all data to memory. If set, the pipeline component will generate and write all inbound data to a temporary file in the specified directory.

Once the file is submitted, the pipeline component will handle closing the file stream and deleting the temporary file. However, if the pipeline component is shut down during a transfer some temporary files may be left in the directory. To ensure optimal performance, server administrators should check the directory regularly and remove old or extraneous files.

This property accepts the "%TEMP%" macro, which will be replaced with the default system temporary directory at runtime. Note: by default, this property is empty and the pipeline component will use memory streams to store all inbound data before submitting it. It is recommended that you use a temporary directory when downloading large batches or batches containing large files to alleviate potential increased memory requirements.

TransportLog Property (Zip 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.

ZipComment Property (Zip Pipeline component)

The comment for the entire zip message.

Data Type

String

Default Value

Remarks

Specifies a global comment for the zip message. Set this property to include a comment in each zipped message the pipeline component creates.

This property is not available in the Disassembler/Decoder.

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

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:


Verbose	The adapter will report all information regarding the transport.
Info	The adapter will report all major operations, as well as all warnings and errors.
Warning	The adapter will report any conditions that could result in unpredictable behavior as well as errors.
Error	The adapter will report all errors that prevent normal operations from completing.
Fatal	The 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:


None	The adapter will not report any logging information.
EventLog	The 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.
File	The 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 (Zip 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.

Zip Config Settings

Append: Specifies whether to append files.

If set to True the adapter will append files to the archive specified by ArchiveFile. ArchiveFile must be set to the location of an archive on disk. If the file does not exist it will be automatically created. The default value is False.

Note: TempPath is not applicable when this is set to True.

ArchiveFile: The location of the archive file on disk.

This setting specifies the location of an archive file on disk. This is only applicable when Append is set to True.

CompressionMethod: Used to set the method of compression.

This is used to specify different compression methods. By default the adapter uses the Deflate compression method (a value of 0). Supported values are:


Value	Method
0	Deflate (default)
1	PPMd
2	bzip2

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.

PlainPassword: Allows you to specify a password stored in plaintext.

By default the Password value will be encrypted with a machine specific key. This secures the password, however the pipeline must be compiled and deployed on the same machine so the same key can be used to decrypt the value. In certain cases you may wish to store the password value in plaintext so decryption is not required at runtime. This setting would be used to specify this like so:

PlainPassword=yourpassword In this case you would not specify any value for Password.

PreserveModifiedTime: Whether or not to preserve the original modified time on extracted files.

Specifies whether or not the modified time of the extracted files use the current time or the original time of the file in the archive.

When set to True (default) the extracted files will have the same modified time as the original file.

When set to False the modified time on the extracted files will be set to the current time.

SSOPassword: Specifies the key name in the SSO configuration that holds the password value.

The pipeline component can be configured to retrieve the password value from a key in an SSO application configuration. To use this approach you must first create a configuration for the application. To do this you can use the SSO Configuration Application MMC Snap-In. After installation follow these steps.

Create an application named "nsoftware.BizTalk".
Add a new key/value pair. The value should hold the password.
Set SSOPassword to the key name.

This approach allows the password to be managed by SSO, and the pipeline component to retrieve the value referenced by the key supplied here.

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.