OpenPGP Pipeline Component

The OpenPGP Pipeline Component provides OpenPGP signing and encryption functionality.

Remarks

The OpenPGP Pipeline Component is used for sending and receiving OpenPGP signed and encrypted messages. The messages may be signed, encrypted, or both.

By default the OpenPGP Pipeline Component will use an internal OpenPGP implementation. This implementation of OpenPGP does not require any additional dependencies and is completely managed. Alternatively the pipeline component may be configured to use an external implementation such as GnuPG. See PGPProviderType for details.

OpenPGP Encoder Pipeline Component

The encoder takes raw messages as input, and generates a signed, encrypted, or signed and encrypted OpenPGP message as output. This pipeline component can be used when creating pipelines to create such messages.

The SignData and EncryptData properties tell the pipeline component which operations should be performed on the message. Set the respective property to true to enable the operation. If signing a message, you will need to specify the private key for signing in the Key property. If encrypting a message, you will need to specify the public key of the recipient in the RecipientKey property. Optionally use the PGPParams property to specify input parameters to the operation.

OpenPGP Decoder Pipeline Component

The decoder takes OpenPGP signed, encrypted, or signed and encrypted messages as input, then verifies and/or decrypts the message. The resulting message will be the raw original message.

The incoming message will be decrypted using the private key in the Key property. Verification is performed automatically when the public key of the signer is specified in the SignerKey property. Optionally use the PGPParams property to specify input parameters to the operation.

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

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.


ASCIIArmor	Specifies whether to use ASCII armor to encode the output message.
CompressionMethod	The compression algorithm used.
EncryptData	Whether or not to encrypt the data.
EncryptingAlgorithm	The encryption algorithm used when encrypting.
HomeDir	The home directory containing the keyring.
Key	Specifies the OpenPGP private key to use for decryption and signing.
Other	Defines a set of configuration settings to be used by the pipeline component.
Passphrase	The passphrase of the private/secret key.
PGPParams	Sets the parameters in the OpenPGP provider.
PGPProvider	The OpenPGP provider provides an interface to the OpenPGP cryptography software.
PGPProviderType	The PGP provider to use.
ProtectedPGPParams	Sets the protected parameters in the OpenPGP provider.
RecipientKey	Specifies the OpenPGP public key to use for encryption.
RecipientUserId	The user Id of the recipient.
RuntimeLicense	Specifies the component runtime license key.
SignData	Whether or not to sign the data.
SigningAlgorithm	The signature hash algorithm used when signing.
TempPath	The path to which temporary files are written at runtime.
TransportLog	Tells the component where and how to report information about its operations.
UserId	The user Id of the key.

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.


HomeDir	The home directory containing the keyring.
Key	Specifies the OpenPGP private key to use for decryption and signing.
Other	Defines a set of configuration settings to be used by the pipeline component.
Passphrase	The passphrase of the private/secret key.
PGPParams	Sets the parameters in the OpenPGP provider.
PGPProvider	The OpenPGP provider provides an interface to the OpenPGP cryptography software.
PGPProviderType	The PGP provider to use.
ProtectedPGPParams	Sets the protected parameters in the OpenPGP provider.
RuntimeLicense	Specifies the component runtime license key.
SignerKey	Specifies the OpenPGP public key to use for signature verification.
SignerUserId	The user Id of the signer.
TempPath	The path to which temporary files are written at runtime.
TransportLog	Tells the component where and how to report information about its operations.
UserId	The user Id of the key.

Config Settings

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


AllowOldPacketType	Whether to allow the older encrypted packet type.
Filename	The original name of the file to encrypt.
ForceV3Signature	Whether to use v3 signatures.
KeySelectionMethod	The method used to select a key for encryption or signing.
LogDebugData	Whether to include debug information in the log.
PipelineOptions	Options defining the validation and protection functionality of the pipeline component.
PublicKeyringFile	The name of the public keyring file.
RecursiveDecryptMode	Whether the encrypted data should be decrypted recursively.
RequireEncryption	Whether an error should be thrown if the message is not encrypted.
RequireSignature	Whether an error should be thrown if the message is not signed.
SecretKeyringFile	The name of the secret keyring file.
SSOPassword	Specifies the key name in the SSO configuration that holds the key passphrase value.
SymmetricPassphrase	The password used for symmetric encryption or decryption.

ASCIIArmor Property (OpenPGP Pipeline component)

Specifies whether to use ASCII armor to encode the output message.

Data Type

Boolean

Default Value

true

Remarks

This property controls whether or not ASCII armoring is used on the output message. The default value is True.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Disassembler/Decoder.

CompressionMethod Property (OpenPGP Pipeline component)

The compression algorithm used.

Data Type

String

Default Value

"zip"

Remarks

This property specifies which compression method is used when generating output. Possible values are:

zip (default)
zlib
bzip2
none or uncompressed

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Disassembler/Decoder.

EncryptData Property (OpenPGP Pipeline component)

Whether or not to encrypt the data.

Data Type

Boolean

Default Value

true

Remarks

If true, then the data will be encrypted by the pipeline component.

This property is not available in the Disassembler/Decoder.

EncryptingAlgorithm Property (OpenPGP Pipeline component)

The encryption algorithm used when encrypting.

Data Type

String

Default Value

"AES128"

Remarks

This property specifies the encryption algorithm used when encrypting. Possible values are:

CAST5
3DES or TripleDES
AES256
AES192
AES128 (default)
BLOWFISH
TWOFISH
IDEA

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Disassembler/Decoder.

HomeDir Property (OpenPGP Pipeline component)

The home directory containing the keyring.

Data Type

String

Default Value

Remarks

This property specifies the directory containing the keyring. A keyring consists of a public (pubring.gpg) and secret keyring (secring.gpg) file. This should be set to the path containing those files.

To use an individual PGP key rather than a keyring file, the Key or RecipientKey properties should be set instead.

Note: Values specified in PGPParams take precedence over values specified in this property.

Key Property (OpenPGP Pipeline component)

Specifies the OpenPGP private key to use for decryption and signing.

Data Type

String

Default Value

Remarks

When using an individual PGP private key instead of a keyring, set this property to the private key. If the key is stored in a key file then this property should be set to the path to that file; alternatively, the ASCII-armored key data can be set directly in this property.

See the HomeDir property for information on using a keyring file.

Note: Values specified in PGPParams take precedence over values specified in this property. However, when using PGPParams the ASCII-armored file data can not be set directly; the key must be stored in a file and a path to a key file must be provided.

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

Passphrase Property (OpenPGP Pipeline component)

The passphrase of the private/secret key.

Data Type

String

Default Value

Remarks

This property specifies the password of the key used for signing and decryption. This property is required when using private/secret keys, whether or not the key has been imported into a keyring.

Note: Values specified in PGPParams take precedence over values specified in this property.

PGPParams Property (OpenPGP Pipeline component)

Sets the parameters in the OpenPGP provider.

Data Type

String

Default Value

Remarks

The PGPParams property is used to specify the parameters required by the OpenPGP provider to perform the OpenPGP operation. Although the parameters needed may vary in different providers, we expect many of the parameters in the following set to be necessary.

Each parameter should be listed on a separate line by itself. The parameters exist in name/value pairs separated by an '=' sign. This may be used to specify all parameters in one location and may also be used to override some component properties.

The following is an example of several parameters that may exist for this property: homedir=C:\myhomedir passphrase=testpgp signature=nondetached


asciiarmor	Controls whether or not ASCII armoring is used on the output message. This will overwrite the value of the ASCIIArmor property.
compressionmethod	Specifies which compression method is used when generating output. Possible values are: zip (default) zlib bzip2 none or uncompressed This parameter is only applicable when PGPProviderType is set to ptInternal. This will overwrite the value of the CompressionMethod property.
encryptingalgorithm	Specifies the encryption algorithm used when encrypting. Possible values are: CAST5 3DES or TripleDES AES256 AES192 AES128 (default) BLOWFISH TWOFISH IDEA This parameter is only applicable when PGPProviderType is set to ptInternal. This will overwrite the value of the EncryptingAlgorithm property.
gpg-path	The path to the OpenPGP executable for the desired implementation. This parameter is not applicable when PGPProviderType is set to ptInternal.
homedir	The directory containing the public keyring, secret keyring and trust database. Please note this defaults to the application preferences directory of the user, hence if the GNUPG provider is being used from a ASP.NET application, homedir should be specified. This will overwrite the value of the HomeDir property.
key	The file where the private/secret PGP key is held. If the key is not stored in a file, the ASCII-armored data can be set directly via the Key property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This parameter is only applicable when PGPProviderType is set to ptInternal. This will overwrite the value of the Key property.
passphrase	The passphrase to access the secret keys in the secret-keyring. This will overwrite the value of the Passphrase property.
recipientkey	The file where the public PGP key for encryption is held. Only applicable for the PGP Encoder component. If the key is not stored in a file, the ASCII-armored data can be set directly via the RecipientKey property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This parameter is only applicable when PGPProviderType is set to ptInternal. This will overwrite the value of the RecipientKey property.
recipient-userid	The identifier used to select a public key within the public keyring when encrypting. This will overwrite the value of the RecipientUserId property.
recipient-userid[i]	An alternative to recipient-userid that allows for multiple recipients to be specified. Each key would be specified with a different index. For example: recipient-userid[0], recipient-userid[1], etc.
signer-userid	The identifier used to select a public key within the public keyring when verifying a signature.
signer-userid[i]	An alternative to signer-userid that allows for multiple recipients to be specified. Each key would be specified with a different index. For example: signer-userid[0], signer-userid[1], etc.
signerkey	The file where the public PGP key for signature verification is held. Only applicable for the PGP Decoder component. If the key is not stored in a file, the ASCII-armored data can be set directly via the RecipientKey property, but the key must be stored in a file to use this field of the PGPParams property. If the key has been imported to a keyring, the homedir field should be set instead. This parameter is only applicable when PGPProviderType is set to ptInternal. This will overwrite the value of the SignerKey property.
signingalgorithm	Specifies the signature hash algorithm used when signing. Possible values are: SHA1 MD5 SHA256 (default) SHA348 SHA512 SHA224 RIPEMD160 This parameter is only applicable when PGPProviderType is set to ptInternal.
userid	The identifier used to select a secret key within the secret-keyring; used for both decryption and signing. This will overwrite the value of the UserId property.

The pipeline component expects the encryption and signing to return an ASCII armored output. Note: GnuPG is the Free Software Foundation's implementation of OpenPGP.

GnuPG is not included with this package, so you should download the latest version from http://www.gnupg.org. You might use GnuPG (or other software) to import your trading partners' public keys, and to import or generate a private key for yourself. These operations are outside the scope of this software, so please see the GnuPG documentation for details.

PGPProvider Property (OpenPGP Pipeline component)

The OpenPGP provider provides an interface to the OpenPGP cryptography software.

Data Type

String

Default Value

Remarks

The library that interfaces to the OpenPGP cryptography software.

When PGPProviderType is set to Internal this property is not used.

When PGPProviderType is set to External this property must be set to a DLL holding the interface to the external application.

External Provider Implementation Notes

When PGPProviderType is set to External the pipeline component uses the provider pattern to interface with external cryptography libraries. An OpenPGP provider is a simple module that allows the adapter to offload OpenPGP operations to the OpenPGP software of your choice. The interface is designed to be generic in its ability to include various OpenPGP software. We include an OpenPGP provider implementation for GnuPG which may be used as a reference to implement other providers.

An OpenPGP provider is simply a class called "nsoftwarePGPProvider" that should have the following methods. The adapter uses reflection to access the methods of the provider. public void SetParam(string name,string value); public byte[] Encrypt(byte[] data); public byte[] Decrypt(byte[] data); public byte[] Sign(byte[] data); public byte[] EncryptAndSign(byte[] data);

PGPProviderType Property (OpenPGP Pipeline component)

The PGP provider to use.

Data Type

Enumeration

Possible Values

External (0)
Internal (1)

Default Value

Remarks

This property specifies which PGP provider is used. By default property is set to ptInternal and all cryptographic operations will be performed by the pipeline component directly using an internal implementation. In this case PGPProvider is not used.

If set to ptExternal the pipeline component will rely on the an external provider such as GnuPG which is accessed through the interface DLL specified by PGPProvider.

External Provider Implementation Notes

ProtectedPGPParams Property (OpenPGP Pipeline component)

Sets the protected parameters in the OpenPGP provider.

Data Type

String

Default Value

Remarks

This should be set to any PGPParams which contain important values that will be hidden from the user configuration.

RecipientKey Property (OpenPGP Pipeline component)

Specifies the OpenPGP public key to use for encryption.

Data Type

String

Default Value

Remarks

When using an individual PGP public key instead of a keyring, set this property to the public key. If the key is stored in a key file then this property should be set to the path to that file; alternatively, the ASCII-armored key data can be set directly in this property.

See the HomeDir property for information on using a keyring file.

This property is not available in the Disassembler/Decoder.

RecipientUserId Property (OpenPGP Pipeline component)

The user Id of the recipient.

Data Type

String

Default Value

Remarks

This specifies the user Id of the recipient's key. This is used to identify the key with which the message is encrypted.

The UserId format is:

FirstName LastName (Comment) <Email>

Not all values are required when selecting or generating a key, but at least FirstName or Email are required.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Disassembler/Decoder.

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

SignData Property (OpenPGP Pipeline component)

Whether or not to sign the data.

Data Type

Boolean

Default Value

false

Remarks

If true, then the data will be signed by the pipeline component.

This property is not available in the Disassembler/Decoder.

SignerKey Property (OpenPGP Pipeline component)

Specifies the OpenPGP public key to use for signature verification.

Data Type

String

Default Value

Remarks

See the HomeDir property for information on using a keyring file.

This property is not available in the Assembler/Encoder.

SignerUserId Property (OpenPGP Pipeline component)

The user Id of the signer.

Data Type

String

Default Value

Remarks

This specifies the user Id of the signer's public key. This is used to identify the key with which the signature should be verified when it has been imported to a keyring.

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Assembler/Encoder.

SigningAlgorithm Property (OpenPGP Pipeline component)

The signature hash algorithm used when signing.

Data Type

String

Default Value

"SHA256"

Remarks

This property specifies the signature hash algorithm used when signing. Possible values are:

SHA1
MD5
SHA256 (default)
SHA384
SHA512
SHA224
RIPEMD160

Note: Values specified in PGPParams take precedence over values specified in this property.

This property is not available in the Disassembler/Decoder.

TempPath Property (OpenPGP Pipeline component)

The path to which temporary files are written at runtime.

Data Type

String

Default Value

Remarks

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

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

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

UserId Property (OpenPGP Pipeline component)

The user Id of the key.

Data Type

String

Default Value

Remarks

This specifies the user Id of the key which is used for signing and decryption. This is used to identify the key when it has been imported to a keyring.

The UserId format is:

FirstName LastName (Comment) <Email>

Not all values are required when selecting or generating a key, but at least FirstName or Email are required.

Note: Values specified in PGPParams take precedence over values specified in this property.

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 (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:


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

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

Proxy Type

The proxy the component will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy such as the Server and the AuthScheme.

Fields

AuthScheme
ProxyAuthSchemes
Default Value: 0

Use the AuthScheme field to tell the adapter which type of authorization to perform when connecting to the proxy. This is only used when the User and Password fields are set.

AuthScheme should be set to authNone (3) when no authentication is expected.

By default, AuthScheme is authBasic (0), and if the User and Password fields are set, the component will attempt basic authentication. If AuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If AuthScheme is set to authProprietary (2), then the authorization token will not be generated by the adapter. Look at the configuration file for the adapter being used to find more information about manually setting this token.

If AuthScheme is set to authNtlm (4), NTLM authentication will be used. This option is only available in the SSL package.

For security reasons, setting this property will clear the values of User and Password.

AutoDetect
Boolean
Default Value: False

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

Password
String
Default Value: ""

A password if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Port
Integer
Default Value: 80

The TCP port for the proxy Server (default 80). See the description of the Server field for details.

Server
String
Default Value: ""

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

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

SSL
ProxySSLTypes
Default Value: 0

Determines when to use SSL for the connection to the proxy. The applicable values are the following:


psAutomatic (0)	Default setting. The connection to the Server is SSL-enabled for 'https' URL-s, and non SSL-enabled for other URL-s.
psAlways (1)	The connection is always SSL-enabled.
psNever (2)	The connection is not SSL-enabled.
psTunnel (3)	The connection is through a tunneling (HTTP) proxy.

User
String
Default Value: ""

A user name, if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Proxy();

public Proxy(string server, int port);

public Proxy(string server, int port, string user, string password);

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

OpenPGP Config 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:


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