/n software Adapters for BizTalk

Questions / Feedback?

OpenPGP Configuration

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.

OpenPGP Configuration Settings

AllowOldPacketType:   Whether to allow the older encrypted packet type.

By default the adapter will only encrypt data using the newer and more secure integrity protected data packet type. Old implementations such as PGP 6.5.8 may require the older less secure data packet type.

When set to True the adapter will read the features from the recipient key to determine if the older packet type is required. If the key does require the old packet type, then the older packet type will be used. If the key does not require the old packet type, then the new integrity protected packet type will still be used.

By default this value is False. This means under no conditions is the older less secure packet type used. The newer integrity protected packet type is always used.

Only enable this setting if you have a requirement to do so.

Filename:   The original name of the file to encrypt.

When encrypting, this configuration setting can be used to specify the original filename of the data to encrypt. If specified, this value is included in the encrypted packet.

This setting is only available in the Encoder.

ForceV3Signature:   Whether to use v3 signatures.

This setting is used to force v3 signatures for compatibility with older PGP implementations (versions 5 through 7).

The default value is False.

This setting is only available in the Encoder.

KeySelectionMethod:   The method used to select a key for encryption or signing.

When more than one key is present this adapter can be configured to automatically select a key based on certain criteria (described below) or allow for manual selection.

0 Automatic selection, first suitable subkey. Expired keys accepted.
1 Automatic selection, first suitable subkey. Expired keys not accepted.
2 Automatic selection, newest suitable subkey. Expired keys not accepted (Default).
99 Manual Selection.

A key's suitability is determined by its usage flags.

Manual Selection

To manually select a key for any operation pass the key's Id in the UserId property.

LogDebugData:   Whether to include debug information in the log.

This setting may be set to True to include detailed debug information in the log. The log mode should also be set to Verbose when using this setting. This may be helpful for troubleshooting purposes. The default value is False.

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.

PublicKeyringFile:   The name of the public keyring file.

This setting may be used to specify an alternative public keyring file. By default the adapter will look for the file "pubring.gpg" in the homedir. Specify this setting to provide an alternative filename. This may be set to a filename without path such as "pubring.pkr" in which case the adapter will search for this file in the homedir. This may also be set to a full path such as "C:\keyring\pubring.pkr".

RecursiveDecryptMode:   Whether the encrypted data should be decrypted recursively.

In some instances data will be encrypted multiple times. This configuration option determines how the adapter will handle this situation. Options are:

0Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default)
1Always attempt recursive decryption.
2Never attempt recursive decryption.

RequireEncryption:   Whether an error should be thrown if the message is not encrypted.

This setting only affects the decoder. By default, unencrypted messages will not cause an error to be thrown. To change this and only allow encrypted messages, set this option to true.

RequireSignature:   Whether an error should be thrown if the message is not signed.

This setting only affects the decoder. By default, unsigned messages will not cause an error to be thrown. To change this and only allow encrypted messages, set this option to true.

SecretKeyringFile:   The name of the secret keyring file.

This setting may be used to specify an alternative secret keyring file. By default the adapter will look for the file "secring.gpg" in the homedir. Specify this setting to provide an alternative filename. This may be set to a filename without path such as "secring.skr" in which case the adapter will search for this file in the homedir. This may also be set to a full path such as "C:\keyring\secring.skr".

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

The pipeline component can be configured to retrieve the key passphrase 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 key passphrase to be managed by SSO, and the pipeline component to retrieve the value referenced by the key supplied here.

SymmetricPassphrase:   The password used for symmetric encryption or decryption.

This setting specifies the passphrase when using symmetric encryption. If a value is provided, symmetric encryption/decryption will be attempted. In this case no keys are used for either encryption or decryption. Only Encrypt and Decrypt are valid operations when a value is set. Sign, SignAndEncrypt, VerifySignature, and DecryptAndVerifySignature are not valid operations when using this option.

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.

Copyright (c) 2022 /n software inc. - All rights reserved.
/n software Adapters for BizTalk - Version 20.0 [Build 8319]