FTP Connector

Properties   Config Settings  

The FTP Component adds SSL-enabled FTP send and receive capabilities to your MuleSoft.

Remarks

The FTP Connector adds a complete FTP client to your Mule Project and enables it with plaintext or SSL-secured file download and upload capability.

FTP Receive Connector

The FTP Receive Connector will establish a connection to a server and download a group of files. A single property must be set: FTPServer. You may also set an FTPPort if the server is not set to the default protocol port. If your FTP server requires authentication, you should set the User, Password and/or Account properties. If you wish to enable SSL, you can turn it on by setting an appropriate SSLCert and SSLStartMode as well as supplying an SSLAcceptServerCert.

The connector will connect to the FTP server every PollingInterval and list the directory specified by RemotePath. All files that match the FileMask will be downloaded and submitted to the Mule Project as individual Mule Messages. In order to guarantee that files are not downloaded multiple times, you may set the DeleteMode. If you wish to do any other PRE- or POST-GET operation, you can specify them as scripts through the BeforeGet and AfterGet properties, respectively.

Download Example

Drag and drop the FTP Receive Connector into the source position of a flow. All that is necessary to get started is to configure the connection settings.

Just as an example, say you want to download a group of files stored on a remote machine in /home/Bob/files. To configure the connector, one option is to specify a RemotePath of /home/Bob/files and an empty FileMask. Since FileMask defaults to *.*, all files in the RemotePath will be downloaded.

The connector will generate one mule event for each file in the remote location. Use a File Write connector behind the FTP Receive connector to write the files to disk.

The received filename is available in the ReceivedFileName attribute on each Mule Message. To write the entire group of files to disk, you can set the Path property of the File Write connector to the following DataWeave code:

"C:\\my\\files\\" ++ attributes.ReceivedFileName

The Content can be left as payload. That is all that is required to begin downloading files.

FTP Send Connector

The FTP Send Connector will establish a connection to a server and upload a file. Two properties must be set: FTPServer and a RemoteFile. If your server does not operate on the default FTP port, you will need to specify the correct port via FTPPort. For servers that do not allow anonymous uploads, you may also need to set User, Password, and/or Account. To enable SSL, you should select a client SSLCert and a SSLAcceptServerCert as well as an SSLStartMode.

The connector will connect to the FTP server whenever it has a message to send. The connector will attempt to upload to the specified RemotePath. In order to prevent parallel processing by another application before your upload is complete, you may need to set a temporary extension via TemporaryUploadExtension. If Overwrite is set to True, the connector will delete or overwrite remote files as necessary to complete the operation.

If you wish to do any other PRE- or POST-PUT operation, you can specify them as scripts through the BeforePut and AfterPut properties, respectively.

Upload Single Example

To get started, add a File Read connector in front of the FTP Send connector and configure it to read a particular target file. The bytes in the payload of the incoming Mule Message are uploaded as a single file.

There is no need to transform the output of the File Read connector before passing it to the FTP Send connector. Configure the FTP Send connector with the above connection settings. That is all that is required to upload the file.

Upload Multiple Example

The Send operation only uploads a single file at a time so we will need to perform the Send operation once for each file.

To get started, add a File List connector to your flow and configure it to list a target folder. The output payload of File List is an Array of file content and a set of attributes for each file.

Behind the File List connector add a For Each Scope and configure it to iterate over the message payload. Inside the For Each Scope, add a FTP Send operation and configure it with the above connection settings.

Set the RemoteFile property dynamically with DataWeave to preserve the uploaded filename. To do this, click the Mule Expression indicator on the RemoteFile property and add the following DataWeave code:

"/home/Spencer/files" ++ attributes.fileName

That is all that is required to upload a group of files.

Receiver Property List


The following is the full list of the properties of the receiver Connector with short descriptions. Click on the links for further details.

AfterConnectA set of FTP commands to be executed immediately after connecting to the FTPServer .
AfterGetA set of FTP commands to be executed after the GET.
BeforeGetA set of FTP commands to be executed before the GET.
DeleteModeControls if and when the remote file is deleted after download.
FileMaskIndicates the type of files to download from the FTP server.
FirewallA set of properties related to firewall access.
FTPPortThe port for the FTP service (default is 21).
FTPServerThe domain name or IP address of the FTP server.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the component.
PassiveControls whether to direct the server into passive mode. Recommended if behind a firewall.
PasswordThe password for login.
PersistentConnectionInstructs the component whether to keep the connection to the server open.
ReceivedFileDateThe date of the remote file received by the FTP component.
ReceivedFileNameThe name of the remote file received by the FTP component.
ReceivedFilePathThe remote path of the file received by the FTP component.
ReceivedFileSizeThe size of the remote file received by the FTP component.
ReceivedFileUserThe user name used by the FTP component when downloading the remote file.
RemotePathThe current path in the FTP server.
RuntimeLicenseSpecifies the component runtime license key.
SSLAcceptServerCertInstructs the component to unconditionally accept the server certificate that matches the supplied certificate.
SSLCertThe certificate to use for client authentication during the SSL handshake.
SSLStartModeDetermines how the component starts the SSL negotiation.
TempPathA temporary local directory where data can be stored before the component processes it.
TimeoutA timeout for the component.
TransferModeThe transfer mode (ASCII or Binary). If the value is 0 (default), the initial server mode will be used.
UserThe user id for login.
UseSimpleDirListInstructs the component to issue the NLST command instead of LIST.

Sender Property List


The following is the full list of the properties of the sender Connector with short descriptions. Click on the links for further details.

AfterConnectA set of FTP commands to be executed immediately after connecting to the FTPServer .
AfterPutA set of FTP commands to be executed after the PUT.
AppendWhether or not the component should append data to the RemoteFile .
BeforePutA set of FTP commands to be executed before the PUT.
FirewallA set of properties related to firewall access.
FTPPortThe port for the FTP service (default is 21).
FTPServerThe domain name or IP address of the FTP server.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the component.
OverwriteWhether or not the component should overwrite files during transfer.
PassiveControls whether to direct the server into passive mode. Recommended if behind a firewall.
PasswordThe password for login.
PersistentConnectionInstructs the component whether to keep the connection to the server open.
ReceivedFileDateThe date of the remote file received by the FTP component.
ReceivedFileNameThe name of the remote file received by the FTP component.
ReceivedFileSizeThe size of the remote file received by the FTP component.
ReceivedFileUserThe user name used by the FTP component when downloading the remote file.
RemoteFileThe name of the destination file on the FTP server for uploading.
RemotePathThe current path in the FTP server.
RemoteTempPathA temporary directory on the server to store files before moving them to RemotePath .
RuntimeLicenseSpecifies the component runtime license key.
SSLAcceptServerCertInstructs the component to unconditionally accept the server certificate that matches the supplied certificate.
SSLCertThe certificate to use for client authentication during the SSL handshake.
SSLStartModeDetermines how the component starts the SSL negotiation.
TimeoutA timeout for the component.
TransferModeThe transfer mode (ASCII or Binary). If the value is 0 (default), the initial server mode will be used.
UserThe user id for login.
UseSimpleDirListInstructs the component to issue the NLST command instead of LIST.

Config Settings


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

AccountThe user account to login with.
AutoSelectDataIPAutomatically select the data connection IP.
CheckFileExistsWhether to check if the remote file exists before uploading.
DownloadCacheFileWhen set, only new files will be downloaded from the server.
DownloadCacheFileDurationThe number of minutes that a file name will remain in the download cache.
EnableFileDetailsComparisonWhether the receive component should consider metadata differences when deciding whether to download a file again.
ExcludeMaskInstructs the component to exclude some files when downloading.
MaxFilesPerPollingIntervalThe maximum number of files that will be downloaded from the server during a single poll.
ModeZCompressionLevelUsed to specify the level of compression used.
PortRangeAllows the specification of a port range the component listens to.
ReusePISSLSessionInDIWhether the PI SSL session will be reused for the DI connection.
ReuseSSLSessionInDIWhether the SSL session will be reused for the DI connection.
UseClearCommandChannelAllows for the Clear Command Channel (CCC) command.
UseClearDataChannelAllows for the PROT C command.
UseEPSVAllows extended passive mode.
UseFSwitchSpecifies whether or not the -F parameter is used when listing directory contents.
UseMLSDUses listings for machine processing.
UseModeZAllows compression to be used when transferring data.
UseProtWhenImplicitSends PROT P to the server.
UseRemoteHostAddressForPassiveInstructs the component to use the FTPServer in passive mode.
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLSecurityFlagsFlags that control certificate verification.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
TcpNoDelayWhether or not to delay when sending packets.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

AfterConnect Property (FTP Connector)

A set of FTP commands to be executed immediately after connecting to the FTPServer .

Data Type

String

Default Value

""

Remarks

AfterConnect is a script that is executed immediately following a successful connection.

The script may contain any number of standard FTP commands.

Each line in the script is treated as a single command. By default, if the connector encounters any errors while executing a command, it will log the error message and will continue to process the script. This behavior can be turned off by inserting "ONERROR FAIL" at any point in the script, which will cause the script to terminate on error but will not interrupt the normal operation of the connector. The default behavior can be restored at any point in the script by inserting the line "ONERROR RESUME".

Valid additional scripting commands are listed below:

cd PathChange the remote directory to the specified path.
del FilenameDelete the specified file from the remote server.
mkdir DirectoryCreate the specified remote directory on the server.
rn Filename NewFilenameRename the remote file specified by Filename to the NewFilename.
move Filename NewFilenameMove the remote file located at Filename to the NewFilename.
rm FilenameRemove the specified file from the remote server.
rmdir DirectoryRemove the remote directory from the server.
touch FilenameCreate the specified file on the server.

AfterGet Property (FTP Connector)

A set of FTP commands to be executed after the GET.

Data Type

String

Default Value

""

Remarks

AfterGet is a script that is executed immediately following each successful FTP GET operation.

The script may contain any number of standard FTP commands.

Each line in the script is treated as a single command. By default, if the connector encounters any errors while executing a command, it will log the error message and will continue to process the script. This behavior can be turned off by inserting "ONERROR FAIL" at any point in the script, which will cause the script to terminate on error but will not interrupt the normal operation of the connector. The default behavior can be restored at any point in the script by inserting the line "ONERROR RESUME".

Valid additional scripting commands are listed below:

cd PathChange the remote directory to the specified path.
del FilenameDelete the specified file from the remote server.
mkdir DirectoryCreate the specified remote directory on the server.
rn Filename NewFilenameRename the remote file specified by Filename to the NewFilename.
move Filename NewFilenameMove the remote file located at Filename to the NewFilename.
rm FilenameRemove the specified file from the remote server.
rmdir DirectoryRemove the remote directory from the server.
touch FilenameCreate the specified file on the server.

This property is not available in the Sender.

AfterPut Property (FTP Connector)

A set of FTP commands to be executed after the PUT.

Data Type

String

Default Value

""

Remarks

AfterPut is a script that is executed immediately following each successful FTP PUT operation.

The script may contain any number of standard FTP commands.

Each line in the script is treated as a single command. By default, if the connector encounters any errors while executing a command, it will log the error message and will continue to process the script. This behavior can be turned off by inserting "ONERROR FAIL" at any point in the script, which will cause the script to terminate on error but will not interrupt the normal operation of the connector. The default behavior can be restored at any point in the script by inserting the line "ONERROR RESUME".

Valid additional scripting commands are listed below:

cd PathChange the remote directory to the specified path.
del FilenameDelete the specified file from the remote server.
mkdir DirectoryCreate the specified remote directory on the server.
rn Filename NewFilenameRename the remote file specified by Filename to the NewFilename.
move Filename NewFilenameMove the remote file located at Filename to the NewFilename.
rm FilenameRemove the specified file from the remote server.
rmdir DirectoryRemove the remote directory from the server.
touch FilenameCreate the specified file on the server.

This property is not available in the Receiver.

Append Property (FTP Connector)

Whether or not the component should append data to the RemoteFile .

Data Type

Boolean

Default Value

false

Remarks

This property controls the connector's upload behavior. When set to TRUE, the connector will append data to the file specified by RemoteFile rather than creating or overwriting it.

This property is not available in the Receiver.

BeforeGet Property (FTP Connector)

A set of FTP commands to be executed before the GET.

Data Type

String

Default Value

""

Remarks

BeforeGet is a script that is executed immediately before each successful FTP GET operation.

The script may contain any number of standard FTP commands.

Each line in the script is treated as a single command. By default, if the connector encounters any errors while executing a command, it will log the error message and will continue to process the script. This behavior can be turned off by inserting "ONERROR FAIL" at any point in the script, which will cause the script to terminate on error but will not interrupt the normal operation of the connector. The default behavior can be restored at any point in the script by inserting the line "ONERROR RESUME".

Valid additional scripting commands are listed below:

cd PathChange the remote directory to the specified path.
del FilenameDelete the specified file from the remote server.
mkdir DirectoryCreate the specified remote directory on the server.
rn Filename NewFilenameRename the remote file specified by Filename to the NewFilename.
move Filename NewFilenameMove the remote file located at Filename to the NewFilename.
rm FilenameRemove the specified file from the remote server.
rmdir DirectoryRemove the remote directory from the server.
touch FilenameCreate the specified file on the server.

This property is not available in the Sender.

BeforePut Property (FTP Connector)

A set of FTP commands to be executed before the PUT.

Data Type

String

Default Value

""

Remarks

BeforePut is a script that is executed immediately before each successful FTP PUT operation.

The script may contain any number of standard FTP commands.

Each line in the script is treated as a single command. By default, if the connector encounters any errors while executing a command, it will log the error message and will continue to process the script. This behavior can be turned off by inserting "ONERROR FAIL" at any point in the script, which will cause the script to terminate on error but will not interrupt the normal operation of the connector. The default behavior can be restored at any point in the script by inserting the line "ONERROR RESUME".

Valid additional scripting commands are listed below:

cd PathChange the remote directory to the specified path.
del FilenameDelete the specified file from the remote server.
mkdir DirectoryCreate the specified remote directory on the server.
rn Filename NewFilenameRename the remote file specified by Filename to the NewFilename.
move Filename NewFilenameMove the remote file located at Filename to the NewFilename.
rm FilenameRemove the specified file from the remote server.
rmdir DirectoryRemove the remote directory from the server.
touch FilenameCreate the specified file on the server.

This property is not available in the Receiver.

DeleteMode Property (FTP Connector)

Controls if and when the remote file is deleted after download.

Data Type

Enumeration

Possible Values

Never (0)
On Success (1)
On Failure (2)
Always (3)


Default Value

0

Remarks

This property informs the connector as to whether or not it should delete a remote files from the server after a successful download. The possible values and their meanings are as follows:

NeverThe remote file is never deleted.
OnSuccessThe remote file is deleted after a successful download.
OnFailureThe remote file is deleted if the transfer fails.
AlwaysThe remote file is deleted regardless of success or failure of the transfer.

Note: the default value is Never for data protection purposes. Unless modified this will result in the connector continuously receiving the same data.

This property is not available in the Sender.

FileMask Property (FTP Connector)

Indicates the type of files to download from the FTP server.

Data Type

String

Default Value

"*.*"

Remarks

As long as the server supports file masks, this property will limit what kinds of files the connector will download from the server. Only files matching the pattern specified in FileMask will be retrieved.

The following special characters are supported for pattern matching:

? Any single character.
* Any characters or no characters (e.g., C*t matches Cat, Cot, Coast, Ct).
[,-] A range of characters (e.g., [a-z], [a], [0-9], [0-9,a-d,f,r-z]).
\ The slash is ignored and exact matching is performed on the next character.

If these characters need to be used as a literal in a pattern, then they must be escaped by surrounding them with brackets []. Note: "]" and "-" do not need to be escaped. See below for the escape sequences:

CharacterEscape Sequence
? [?]
* [*]
[ [[]
\ [\]

For example, to match the value [Something].txt, specify the pattern [[]Something].txt.

This property is not available in the Sender.

Firewall Property (FTP Connector)

A set of properties related to firewall access.

Data Type

Firewall

Remarks

This is a Firewall type property which contains fields describing the firewall through which the connector will attempt to connect.

FTPPort Property (FTP Connector)

The port for the FTP service (default is 21).

Data Type

Integer

Default Value

21

Remarks

A valid port number (a value between 1 and 65535) is required for the connection to take place.

FTPServer Property (FTP Connector)

The domain name or IP address of the FTP server.

Data Type

String

Default Value

""

Remarks

The FTPServer property specifies the IP address (IP number in dotted internet format) or Domain Name of the FTP server.

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

LogFile Property (FTP Connector)

The file to write logging information to at runtime.

Data Type

String

Default Value

""

Remarks

To write logging information to a file instead of using the connector's logging API, set this property to a valid file on disk and set the LogType property to "File".

LogMode Property (FTP Connector)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)


Default Value

3

Remarks

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

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

LogType Property (FTP Connector)

How information gets logged during component execution.

Data Type

Enumeration

Possible Values

None (0)
Console (1)
File (2)


Default Value

1

Remarks

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

NoneThe connector will not report any logging information.
ConsoleThe connector will report all logging information to the console.
FileThe connector will report all logging information to a file. The desired file must be specified in the LogFile when this type has been selected.

Other Property (FTP Connector)

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

Data Type

String

Default Value

""

Remarks

The connector accepts one or more 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 connector, 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

Overwrite Property (FTP Connector)

Whether or not the component should overwrite files during transfer.

Data Type

Boolean

Default Value

true

Remarks

This property is a value indicating whether or not the connector should overwrite files on the server if they already exist. If Overwrite is false, an error will be thrown whenever RemoteFile exists before an upload operation.

This property is not available in the Receiver.

Passive Property (FTP Connector)

Controls whether to direct the server into passive mode. Recommended if behind a firewall.

Data Type

Boolean

Default Value

true

Remarks

When false, FTP communications take place in Active mode. In an Active mode connection, data connections are established from server to client on an IP address and port specified by the client in a PORT command to the server.

Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client connector expects them. By default, Passive is set to TRUE, and the connector will request that FTP communications take place in Passive mode. In Passive mode, the connector will use the PASV instead of the PORT command and data connections will be established from the client to the server.

Password Property (FTP Connector)

The password for login.

Data Type

Password

Default Value

""

Remarks

This property must be set before the connector connects to the FTP server.

PersistentConnection Property (FTP Connector)

Instructs the component whether to keep the connection to the server open.

Data Type

Boolean

Default Value

false

Remarks

If set to true, the connector will first attempt to use an existing connection. If no such connection exists, it will create a new connection. When the connector completes, it will persist the connection so that the connector will reuse it during the next polling interval. Setting this property to true can improve performance if you are polling very frequently.

ReceivedFileDate Property (FTP Connector)

The date of the remote file received by the FTP component.

Data Type

String

Default Value

""

Remarks

This value contains the date of the remote file being received by the FTP connector. It can be read from the context of a message being received by an FTP connector receive location.

This value contains the date of the remote file being received by the FTP connector.

ReceivedFileName Property (FTP Connector)

The name of the remote file received by the FTP component.

Data Type

String

Default Value

""

Remarks

This is the filename returned by the server.

This value is also placed in the File.ReceivedFileName and the FTP.ReceivedFileName context properties. This is to ensure compatibility with other connectors that poll those context properties when filling out macros such as %SourceFileName%.

This is the filename returned by the server.

ReceivedFilePath Property (FTP Connector)

The remote path of the file received by the FTP component.

Data Type

String

Default Value

""

Remarks

This is the remote path of the file returned by the server. It can be read from the context of a message being received by an FTP connector receive location.

This property is not available in the Sender.

ReceivedFileSize Property (FTP Connector)

The size of the remote file received by the FTP component.

Data Type

Integer

Default Value

0

Remarks

This value contains the size of the remote file being received by the FTP connector. It can be read from the context of a message being received by an FTP connector receive location.

This value contains the size of the remote file being received by the FTP connector.

ReceivedFileUser Property (FTP Connector)

The user name used by the FTP component when downloading the remote file.

Data Type

String

Default Value

""

Remarks

This property contains the value of the User used by the FTP connector to authenticate before downloading the remote file. It can be read from the context of a message being received by an FTP connector receive location.

This property contains the value of the User used by the FTP connector to authenticate before downloading the remote file.

RemoteFile Property (FTP Connector)

The name of the destination file on the FTP server for uploading.

Data Type

String

Default Value

""

Remarks

The RemoteFile is either an absolute file path, or a relative path based on RemotePath.

This property is not available in the Receiver.

RemotePath Property (FTP Connector)

The current path in the FTP server.

Data Type

String

Default Value

""

Remarks

The RemotePath can be used to set the working directory by setting it to either an absolute directory path or a path relative to the initial remote directory when the connector connects to the FTP server.

RemoteTempPath Property (FTP Connector)

A temporary directory on the server to store files before moving them to RemotePath .

Data Type

String

Default Value

""

Remarks

If a value is specified, the connector will directly upload the file to RemoteTempPath. Once the file transfer is complete, the connector will move the file to the RemotePath.

This property is not available in the Receiver.

RuntimeLicense Property (FTP Connector)

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

SSLAcceptServerCert Property (FTP Connector)

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.

Data Type

Certificate

Remarks

If it finds any issues with the certificate presented by the server, the connector will normally terminate the connection with an error. You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

This property is used to set a Public Key Certificate.

Ordinarily, the system will attempt to locate the public key in trusted certificate stores in the system registry. If a match is found, the certificate is trusted, and the process proceeds without error. If the certificate is not trusted, the connector will report an error.

You may explicitly set a public key, either to accept a key that is not installed on the system, or to ensure that a specific key is presented. Public key certificates may be loaded from the machine registry or from file.

Note: You may also set the Accept Any field to Yes without opening the certificate selection dialog to force the connector to unilaterally authenticate any server during the security handshake. It is strongly recommended that you use this only for testing purposes. Set the LogMode to Info to cause the connector to report the server's credentials to Location.

SSLCert Property (FTP Connector)

The certificate to use for client authentication during the SSL handshake.

Data Type

Certificate

Remarks

This property is used to assign a specific certificate for SSL client authentication.

This field is used to set a Private Key Certificate.

Private key certificates may be loaded from the registry, from files in PKCS#12 format, or from a PEM file format.

SSLStartMode Property (FTP Connector)

Determines how the component starts the SSL negotiation.

Data Type

Enumeration

Possible Values

Automatic (0)
Implicit (1)
Explicit (2)
None (3)


Default Value

0

Remarks

The SSLStartMode property may have one of the following values:

AutomaticIf the remote port is set to the standard plaintext port of the protocol (where applicable), the connector will behave the same as if SSLStartMode is set to Explicit. In all other cases, SSL negotiation will be implicit (Implicit).
ImplicitThe SSL negotiation will start immediately after the connection is established.
ExplicitThe connector will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.
NoneNo SSL negotiation, no SSL security. All communication will be in plaintext mode.

TempPath Property (FTP Connector)

A temporary local directory where data can be stored before the component processes it.

Data Type

String

Default Value

""

Remarks

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

Once the file is submitted, the connector will handle closing the file stream and deleting the temporary file. However, if the connector 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. Note: by default, this property is empty and the connector 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.

This property is not available in the Sender.

Timeout Property (FTP Connector)

A timeout for the component.

Data Type

Integer

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the connector will wait for the operation to complete before returning control.

If Timeout expires, and the operation is not yet complete, the connector fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behavior of the connector may be changed to absolute timeouts, i.e. the connector will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by the AbsoluteTimeout configuration setting.

The default value for the Timeout property is 60 (seconds).

TransferMode Property (FTP Connector)

The transfer mode (ASCII or Binary). If the value is 0 (default), the initial server mode will be used.

Data Type

Enumeration

Possible Values

Default (0)
ASCII (1)
Binary (2)


Default Value

0

Remarks

The valid options for the TransferMode property are as follows:

Default The initial mode of the FTP server is taken. No change.
ASCII Files are transferred in ASCII mode (TYPE A).
Binary Files are transferred in Binary mode (TYPE I).

User Property (FTP Connector)

The user id for login.

Data Type

String

Default Value

""

Remarks

This property must be set before the connector connects to the FTP server.

UseSimpleDirList Property (FTP Connector)

Instructs the component to issue the NLST command instead of LIST.

Data Type

Boolean

Default Value

false

Remarks

When this is set to true, the connector will send the NLST command to the server. This tells the server to return a more simply formatted listing. If the server's directory listing can not be parsed when this is false, setting this to true will be helpful.

Certificate Type

The digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Store
String

Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType field specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field in order to specify client certificates. If Store has a value, and Subject is set, a search for a certificate is initiated. Please refer to the Subject field for details.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.
SPCSoftware publisher certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

StorePassword
String

Default Value: ""

If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.

StoreType
CertStoreTypes

Default Value: 0

The type of certificate store for this certificate.

The connector supports both public and private keys in a variety of formats. When the cstAuto value is used, the connector 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 connector. 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.

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 connector 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.

Config Settings (FTP Connector)

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

FTP Config Settings

Account:   The user account to login with.

Some servers may require an Account for logon or in order to access specific privileges, like uploading or deleting files.

AutoSelectDataIP:   Automatically select the data connection IP.

This setting controls the selection logic of the data connection. By default, this value is True and the connector will attempt to determine the best IP for the data connection based on the returned value from the server. It is recommended to leave this value set to True unless there is a reason to disable it.

In many cases, FTP servers are not configured to return a valid public IP in the PASV response. When Secure Sockets Layer/Transport Layer Security (SSL/TLS) is used any network address translation (NAT) done by the firewall cannot occur. The result is the client may receive an IP that is not accessible.

This setting is designed to allow the connection to succeed in as many cases as possible. When the IP for the data connection is received from the server, the connector will inspect the value. If the received value is not within the known private IP ranges, the connector will use it, assuming it is a valid public IP. If the received value is a private IP, the connector will instead assume the data connection should be established to the same IP as the command connection (true in almost all cases).

When this setting is False, the connector will not perform any checks on the received value. When set to False, UseRemoteHostAddressForPassive is applicable.

CheckFileExists:   Whether to check if the remote file exists before uploading.

If set to "FALSE" the adapter will not perform a directory listing to check for the presence of the file on the server before uploading the file.

NOTE: This setting is only applicable to the FTP Transmitter.

DownloadCacheFile:   When set, only new files will be downloaded from the server.

This may be set to the location of a file on disk that will hold the names of files that were previously downloaded from the server. On each PollingInterval the connector will check to see if the file on the server exists in this list. If the file exists in this list, it is determined that the file was previously downloaded and is not downloaded on the current polling interval. The list is automatically updated on each polling interval. Please see DownloadCacheFileDuration and EnableFileDetailsComparison for more configuration options.

DownloadCacheFileDuration:   The number of minutes that a file name will remain in the download cache.

If a file name is added to the DownloadCacheFile and is not seen on the server again within DownloadCacheFileDuration minutes, it will be removed from the cache. This can prevent the download cache file from growing too large in certain cases.

The default value is 0, meaning that files will never be removed.

This setting is only applicable if DownloadCacheFile is set.

EnableFileDetailsComparison:   Whether the receive connector should consider metadata differences when deciding whether to download a file again.

This setting is used in conjunction with DownloadCacheFile, and is only available on the receive connector. If DownloadCacheFile is enabled, this setting can be used to control how the receive connector uses the download file cache information when deciding whether to download a file again. (Similar to the "Enable Timestamp Comparison" property on Microsoft's FTP BizTalk Adapter.)

If this is set to False, the receive connector will not download a file again if the cache contains any information about it (that is, if it has been downloaded before).

If this is set to True, the receive connector will check the metadata of the remote file against its cached metadata, and will download the file again if any of the metadata differs.

ExcludeMask:   Instructs the connector to exclude some files when downloading.

This configuration setting is used to specify a mask to exclude certain files when downloading. If a file matches both this mask and FileMask, the file will be not be downloaded.

MaxFilesPerPollingInterval:   The maximum number of files that will be downloaded from the server during a single poll.

By default, the connector will download all available files (matching any filemasks) when polling the target directory. To limit the number of files that will be downloaded in a single poll, set this to the maximum number.

Note that to avoid downloading the same subset of files each poll, either DownloadCacheFile or DeleteMode should also be used.

ModeZCompressionLevel:   Used to specify the level of compression used.

The default value is 7. Valid values range from 0 to 9. A higher value indicates that a higher compression level is being used. This is valid only when UseModeZ is set to True.

PortRange:   Allows the specification of a port range the connector listens to.

When set to use active mode (Passive = False), the connector uses any available port to listen to incoming connections from the server. You can override this behavior by setting PortRange to a value containing the range of ports the connector will be listening to.

The range is provided as start-end, for instance: "1024-" stands for anything higher than 1024, "1024-2048" stands for ports between 1024 and 2048 inclusive, "4000-4010, 50000-50010" stands for ports between 4000 and 40010 or between 50000 and 50010.

ReusePISSLSessionInDI:   Whether the PI SSL session will be reused for the DI connection.

When set to True, the connector will reuse the PI SSL session when creating the DI connection. The default value for this configuration setting is False, in which case, the connector will create a separate SSL session for the DI connection.

ReuseSSLSessionInDI:   Whether the SSL session will be reused for the DI connection.

When set to True (default), the connector will ask the server to reuse the existing DI SSL session. When set to False, a new SSL session will always be created for the DI connection.

UseClearCommandChannel:   Allows for the Clear Command Channel (CCC) command.

When set, the connector will send the CCC command to the server requesting a clear (unprotected) command channel.

UseClearDataChannel:   Allows for the PROT C command.

When this is set, the connector will use a clear (unprotected) data channel by sending the PROT C command to the server.

UseEPSV:   Allows extended passive mode.

When set, extended passive mode will be used.

UseFSwitch:   Specifies whether or not the -F parameter is used when listing directory contents.

This is only applicable when UseSimpleDirList is set to true. When UseSimpleDirList is true, the connector issues the command "NLST -F <filemask>". The -F parameter tells the server to omit folder names from the response. Some server do not support the -F parameter. To disable the use of the -F parameter set UseFSwitch to False. The default value is True.

UseMLSD:   Uses listings for machine processing.

When this is set to True the connector will list files in the directory using the MLSD command. This command is an extension to the protocol which defines a more standardized and reliable directory listing format. Not all servers support this command. The default value is False.

UseModeZ:   Allows compression to be used when transferring data.

The default value is False. When set to True, the connector will issue the MODE Z command to the FTP server. This will enable deflate compression so that all data transferred are first compressed either by the server (when downloading) or by the connector (when uploading). Note: Not all servers support this feature.

UseProtWhenImplicit:   Sends PROT P to the server.

The connector will send the PROT P command to the server explicitly indicating that the data channel will be protected when this is set. This only applies when the SSLStartMode is set to sslImplicit.

UseRemoteHostAddressForPassive:   Instructs the connector to use the FTPServer in passive mode.

This setting is only used when Passive is true. When this is set to false (default), the connector parses the remote host to send replies to from the previous response from the server. If this is true, the connector uses the value at FTPServer instead.

SSL Config Settings

ReuseSSLSession:   Determines if the SSL session is reused.

If set to true, the connector will reuse the context if and only if the following criteria are met:

  • The target host name is the same.
  • The system cache entry has not expired (default timeout is 10 hours).
  • The application process that calls the function is the same.
  • The logon session is the same.
  • The instance of the connector is the same.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the connector will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseInternalSecurityAPI is False (default): // The "Other" property could contain ONE of the following lines: SSLEnabledCipherSuites=* SSLEnabledCipherSuites=CALG_AES_256 SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES Possible values when UseInternalSecurityAPI is False (default) include:

  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when UseInternalSecurityAPI is True: // The "Other" property could contain ONE of the following lines: SSLEnabledCipherSuites=* SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA Possible values when UseInternalSecurityAPI is True include:
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

If SSLEnabledProtocols is configured to use TLS 1.3 the following values are supported:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384

SSLEnabledCipherSuites is used together with SSLCipherStrength.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.312288 (Hex 3000) (Experimental)
TLS1.23072 (Hex C00) (Default)
TLS1.1768 (Hex 300) (Default)
TLS1 192 (Hex C0) (Default)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

Note: TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This setting specifies whether the transport log contains the full certificate chain. By default this value is False and only the leaf certificate will be present.

If set to True all certificates returned by the server will be present in the transport log. This includes the leaf certificate, any intermediate certificate, and the root certificate.

Note: When UseInternalSecurityAPI is set to True this value is automatically set to True. This is needed for proper validation when using the internal provider.

SSLSecurityFlags:   Flags that control certificate verification.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown Certificate Authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown Certificate Authority revocation status.
0x00000800Ignore unknown Root revocation status.
0x00008000Allow test Root certificate.
0x00004000Trust test Root certificate.
0x80000000Ignore non-matching CN (certificate CN not-matching server name).

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the connector will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the connector will fail with an error.

The format of this value is a comma separated list of hash-signature combinations. For instance: // The "Other" could contain ALL of these lines: UseInternalSecurityAPI=true SSLEnabledProtocols=3072 TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa The default value for this setting is "sha1-rsa,sha1-dsa,sha224-rsa,sha224-dsa,sha256-rsa,sha256-dsa,sha384-rsa,sha384-dsa,sha512-rsa,sha512-dsa".

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

TLS12SupportedGroups:   The supported groups for ECC.

This setting specifies a comma separated list of named groups used in TLS 1.2 for ECC.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

When using TLS 1.2 and UseInternalSecurityAPI is set to True, the values refer to the supported groups for ECC. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. The groups specified here will have key share data pregenerated locally before establishing a connection. This can prevent an additional round trip during the handshake if the group is supported by the server.

The default value is set to balance common supported groups and the computational resources required to generate key shares. As a result only some groups are included by default in this setting.

Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used which is not present in this list it will incur an additional round trip and time to generate the key share for that group.

In most cases this setting does not need to be modified. This should only be modified if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448"
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
The default value is rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3.
TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

This setting specifies a comma separated list of named groups used in TLS 1.3 for key exchange. This setting should only be modified if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_x448,ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1,ffdhe_2048,ffdhe_3072,ffdhe_4096,ffdhe_6144,ffdhe_8192

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448" (default)
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096" (default)
  • "ffdhe_6144" (default)
  • "ffdhe_8192" (default)

General Config Settings

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

LocalHost:   The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost configuration contains the name of the local host as obtained by the Gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the connector initiate connections (or accept in the case of server connectors) only through that interface.

If the connector is connected, the LocalHost configuration shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

TcpNoDelay:   Whether or not to delay when sending packets.

When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this config is set to false.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to False, the connector will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to True tells the connector to use the internal implementation instead of using the system security libraries.

This setting is set to False by default on all platforms.