IPWorks SFTP 2020 Android Edition

Questions / Feedback?

Sftpserver Configuration

The component 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 component, access to these internal properties is provided through the Config method.

SFTPServer Configuration Settings

DirListBufferSize[ConnectionId]:   The number of entries to be returned in one response to a request for a directory listing.

The default value for this configuration setting is 1, which means that the component will return one entry at a time in response to a request for a directory listing. Changing this value will allow the component to bundle multiple entries into a single response.

MaskSensitive:   Masks passwords in logs.

The default value is false. When set to true the component will mask passwords that would otherwise appear in its logs.

ProtocolVersion:   The highest allowable SFTP version to use.

This governs the highest allowable SFTP version to use when negotiating the version with the client. The default value is 3 as this is the most common version. The component supports values from 3 to 6.

RestrictUserToHomeDir[ConnectionId]:   Whether to restrict the user to their home directory.

When True, this setting will restrict the user to the path specified by the "HomeDir" parameter in the SSHUserAuthRequest event. When False (default), the user will be able to navigate outside of the home directory. "ConnectionId" specifies the connection to which the restriction applies.


sftpserver.Config("RestrictUserToHomeDir[" + e.ConnectionId + "]=true");

Example

If the RootDirectory property of a certain SFTP server is set to /, then the directory structure of the server might look like this...


Root Directory: /

bin
boot
etc
home
  user1
    testfolder
When RestrictUserToHomeDir is set to True and the "HomeDir" parameter is set to /home/user1, User 1 will land in the home directory and see the following file system when it connects:
Home Directory: /home/user1

/testfolder
The client will only be able to perform operations against /home/user1 and its children but the client can see its working directory relative to the server root directory.

ServerEOL:   Specifies the line endings used in files on the server.

This setting is used to inform the connecting client what line endings are used in the files on the system. This is only applicable when ProtocolVersion is set to 4 or higher and a connecting client negotiates protocol version 4 or higher. When a client negotiates version 4 or higher this value is reported using the "newline" protocol convention. The client may use that to transform line endings when downloading. The default value is CrLF.

SFTPErrorMessage[ConnectionId]:   Specifies the error message to be returned to the client.

If an SFTP operation would return an error to the client (e.g., permission denied, file does not exist, etc) then this configuration option can be used to specify the error message to be returned to the client. This configuration option is only effective when set within an event that uses the "StatusCode" field.

UserRootDirectory[ConnectionId]:   The path of the server root directory for a particular user.

When set to a subdirectory of the server root, this setting will override the server RootDirectory for a particular user. The "HomeDir" parameter of the SSHUserAuthRequest event will represent the initial path of the client relative to the UserRootDirectory. "ConnectionId" specifies the connection to which the restriction applies.

sftpserver.Config("UserRootDirectory[" + e.ConnectionId + "]=" + userRootDirectory );

Example

If the RootDirectory property of a certain SFTP server is set to /, then the directory structure of the server might look like this...


Root Directory: /

bin
boot
etc
home
  user1
    testfolder
When UserRootDirectory is set to /home/user1 and the HomeDir event parameter is set to /, when User 1 connects they will land in the home directory and see the following file system:
Home Directory: /

/testfolder
The client will only be able to perform operations against / and its children and the client cannot see its working directory relative to the server root directory.

SSHDaemon Configuration Settings

AltSSHCertCount:   The number of records in the AltSSHCert configuration settings.

This configuration setting controls the size of the following arrays:

The array indices start at 0 and end at AltSSHCertCount - 1.

The AltSSHCert configuration settings are used to specify alternative digital certificates to the one set using the SSHCert. The server will determine the certificate to use during SSH negotiation based on the public key algorithm requested by the connecting client. A certificate with a private key is required for session authentication and encryption.

These are the server's certificates, and must be set prior to setting Listening to True.

AltSSHCertStore[i]:   The name of the certificate store.

The name of the certificate store. This is used when specifying an alternative SSHCert.

The AltSSHCertStoreType specifies the type of the certificate store specified by AltSSHCertStore. IF the store is password protected, specify the password in the AltSSHCertStorePassword.

AltSSHCertStore is used in conjunction with the AltSSHCertSubject field in order to specify the certificate.

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.

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

AltSSHCertStorePassword[i]:   The password used to open the certificate store.

If the certificate store is of a type that requires a password, this setting can be used to specify that password. This is used when specifying an alternative SSHCert

AltSSHCertStoreType[i]:   The type of certificate store.

This specifies the type of certificate store. This is used when specifying an alternate SSHCert. Possible values are:

0 User - 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 Machine - For Windows, this specifies that the certificate store is a machine store. Note: this store type is not available in Java.
2 PFXFile - The certificate store is the name of a PFX (PKCS12) file containing certificates.
3 PFXBlob - The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) format.
4 JKSFile - 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 JKSBlob - 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 PEMKeyFile - The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 PEMKeyBlob - The certificate store is a string (binary or base64-encoded) that contains a private key and an optional certificate.
14 PPKFile - The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 PPKBlob - The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 XMLFile - The certificate store is the name of a file that contains a certificate in XML format.
17 XMLBlob - The certificate store is a string that contains a certificate in XML format.

AltSSHCertSubject[i]:   The alternative certificate subject.

The subject of the certificate. This is used when specifying an alternative SSHCert.

DefaultIdleTimeout:   Specifies the default idle timeout for inactive clients.

This property specifies the idle timeout (in seconds) for clients. When set to a positive value the component will disconnect idle clients after the specified timeout.

If set to 0 (default) no idle timeout is applied.

KeyboardInteractivePrompts[ConnectionId]:   Specifies custom keyboard-interactive prompts for particular connections.

By default, setting the KeyboardInteractivePrompts property will cause those prompts to be used for every user attempting to connect. This setting can be used to override the KeyboardInteractivePrompts property and provide unique prompts for certain connections.

This setting takes a list of prompts to display to the client, and each prompt includes an 'echo' parameter to specify whether or not to echo the client's response to the prompt. The prompt itself and the echo parameter should be separated by a comma (","), and each prompt should be separated by a semi-colon (";"). For example:

"KeyboardInteractivePrompts[connId]=First prompt,echo=false;Second prompt,echo=true"

This config can be set anywhere in code, but it is necessary to know the ConnectionId for the specific connection beforehand; as such, it is generally recommended to set this config inside the SSHUserAuthRequest event. Since connecting clients initially attempt to connect with and AuthMethod of 'none' (with the understanding that this attempt will fail, and the SSH server will advertise which authentication methods it supports), It is recommended to check the AuthMethod, User, and ConnectionId parameters of the SSHUserAuthRequest event and set this config accordingly.

When SSHDaemon displays keyboard-interactive prompts, it will first check to see if this config is populated for the current ConnectionId. If it is, the prompts set here will be used instead of those set in the KeyboardInteractivePrompts property. Otherwise, the KeyboardInteractivePrompts property will function as normal.

KeyRenegotiationThreshold:   Sets the threshold for the SSH Key Renegotiation.

This property allows you to specify the threshold, in the number of bytes, for the SSH Key Renegotiation. The default value for this property is set to 1 GB.

Example (for setting the threshold to 500 MB):

SSHComponent.Config("KeyRenegotiationThreshold=524288000")

LogLevel:   Specifies the level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No messages are logged.
1 (Info - Default) Informational events such as SSH handshake messages are logged.
2 (Verbose) Detailed data such as individual packet information is logged.
3 (Debug) Debug data including all relevant sent and received bytes are logged.

MaxAuthAttempts:   The maximum authentication attempts allowed before forcing a disconnect.

This setting specifies the maximum amount of authentication attempts that will be allowed before forcibly disconnecting the client.

ServerSSHVersionString:   The SSH version string sent to connecting clients.

This setting specifies the version string value that is sent to all connecting clients. This may be set to specify server specific information. The default value is "SSH-2.0-IPWorks SSH Daemon 2016". When setting your own value it must begin with "SSH-2.0-" as this is a standard format that specifies the supported SSH version.

SSHKeepAliveCountMax:   The maximum number of keep alive packets to send without a response.

This setting specifies the maximum number of keep alive packets to send when no response is received. Normally a response to a keep alive packet is received right away. If no response is received the component will continue to send keep alive packets until SSHKeepAliveCountMax is reached. If this is reached the component will assume the connection is broken and disconnect. The default value is 5.

SSHKeepAliveInterval:   The interval between keep alive packets.

This setting specifies the number of seconds between keep alive packets. If set to a positive value the component will send a SSH keep alive packet after KeepAliveInterval seconds of inactivity. This setting only takes effect when there is no activity, if any data is sent or received over the connection it will reset the timer.

The default value is 0 meaning no keep alives will be sent.

Note: The SSHREVERSETUNNEL component uses a default value of 30.

SSHKeyExchangeAlgorithms:   Specifies the supported key exchange algorithms.

This may be used to specify the list of supported Key Exchange algorithms used during SSH negotiation. The value should contain a comma separated list of algorithms. Supported algorithms are:

  • curve25519-sha256
  • curve25519-sha256@libssh.org
  • diffie-hellman-group1-sha1
  • diffie-hellman-group14-sha1
  • diffie-hellman-group14-sha256
  • diffie-hellman-group16-sha512
  • diffie-hellman-group18-sha512
  • diffie-hellman-group-exchange-sha256
  • diffie-hellman-group-exchange-sha1
  • ecdh-sha2-nistp256
  • ecdh-sha2-nistp384
  • ecdh-sha2-nistp521
The default value is: curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group14-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha256,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,ecdh-sha2-nistp256,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,ecdh-sha2-nistp384,ecdh-sha2-nistp521.
SSHMacAlgorithms:   Specifies the supported Mac algorithms.

This may be used to specify an alternate list of supported Mac algorithms used during SSH negotiation. This also specifies the order in which the Mac algorithms are preferred. The value should contain a comma separated list of algorithms. Supported algorithms are:

  • hmac-sha1
  • hmac-md5
  • hmac-sha1-96
  • hmac-md5-96
  • hmac-sha2-256
  • hmac-sha2-256-96
  • hmac-sha2-512
  • hmac-sha2-512-96
  • hmac-ripemd160
  • hmac-ripemd160-96
  • hmac-sha2-256-etm@openssh.com
  • hmac-sha2-512-etm@openssh.com
The default value is hmac-sha2-256,hmac-sha2-512,hmac-sha1,hmac-md5,hmac-ripemd160,hmac-sha1-96,hmac-md5-96,hmac-sha2-256-96,hmac-sha2-512-96,hmac-ripemd160-96,hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com.
SSHPublicKeyAlgorithms:   Specifies the supported public key algorithms.

This setting specifies the allowed public key algorithms. This list controls only the public key algorithm used when authenticating to the server. This list has no bearing on the public key algorithms that can be used to authenticate the client. The default value is ssh-ed25519,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,rsa-sha2-256,rsa-sha2-512,ssh-rsa,ssh-dss,x509v3-sign-rsa,x509v3-sign-dss.

SSHVersionPattern:   The pattern used to match the remote host's version string.

This configuration setting specifies the pattern used to accept or deny the remote host's SSH version string. It takes a comma-delimited list of patterns to match. The default value is "*SSH-1.99-*,*SSH-2.0-*" and will accept connections from SSH 1.99 and 2.0 hosts. As an example, the below value would accept connections for SSH 1.99, 2.0, and 2.99 hosts.

*SSH-1.99-*,*SSH-2.0-*,*SSH-2.99-*
UserAuthBanner[ConnectionId]:   A custom user authentication banner.

This setting specifies a custom user authentication banner, which may be sent to give the client more information regarding an authentication attempt. "connectionId" specifies the particular connection to send the message to. This configuration option is only effective when set within the SSHUserAuthRequest event.

IPDaemon Configuration Settings

AllowedClients:   A comma-separated list of host names or IP addresses that can access the component.

This setting defines a comma-separated list of host names or IPv4 addresses that may access the component. The wildcard character "*" is supported. The default value is "*" and all connections are accepted.

When a client connects, the client's address is checked against the list defined here. If there is no match, the ConnectionRequest event fires with an Accept value set to False. If no action is taken within the ConnectionRequest event, the client will be disconnected.

BindExclusively:   Whether or not the component considers a local port reserved for exclusive use.

If this is true (default), the component will bind to the local port with the ExclusiveAddressUse option set, meaning that nothing else can bind to the same port. Also the component will not be able to bind to local ports that are already in use by some other instance and attempts to do so will result in failure.

CloseStreamAfterTransfer:   If true, the component will close the upload or download stream after the transfer.

This setting determines whether the input or output stream is closed after the transfer completes. When set to True (default), all streams will be closed after a transfer is completed. In order to keep streams open after the transfer of data, set this to False. the default value is True.

DefaultConnectionTimeout:   The inactivity timeout applied to the SSL handshake.

This setting specifies the inactivity (in seconds) to apply to incoming SSL connections. When set to a positive value if the other end is unresponsive for the specified number of seconds the connection will timeout. This is not applicable to the entire handshake, only the inactivity of the connecting client during the handshake if a response is expected and none is received within the timeout window. The default value is 0 and no connection specific timeout is applied.

Note: This is only applicable to incoming SSL connections. This should only be set if there is a specific reason to do so.

InBufferSize:   The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. Increasing the value of the InBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

InBufferSize is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

KeepAliveInterval:   The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.

A TCP keep-alive packet will be sent after a period of inactivity as defined by KeepAliveTime. If no acknowledgement is received from the remote host the keep-alive packet will be re-sent. This setting specifies the interval at which the successive keep-alive packets are sent in milliseconds. This system default if this value is not specified here is 1 second. This setting is applicable to all connections.

Note: This value is not applicable in Java or MAC.

KeepAliveTime:   The inactivity time in milliseconds before a TCP keep-alive packet is sent.

By default the operating system will determine the time a connection is idle before a TCP keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many cases a shorter interval is more useful. Set this value to the desired interval in milliseconds. This setting is applicable to all connections.

Note: This value is not applicable in Java.

MaxConnections:   The maximum number of connections available.

The maximum number of connections available. This property must be set before Listening is set to True, and once set, it can no longer be changed for the current instance of the component. The maximum value for this setting is 100,000 connections. Use this setting with caution. Extremely large values may impact performance.

OutBufferSize:   The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. Increasing the value of the OutBufferSize setting can provide significant improvements in performance in some cases.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the component is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

OutBufferSize is shared among incoming connections. When the property is set, the corresponding value is set for incoming connections as they are accepted. Existing connections are not modified.

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.

UseIPv6:   Whether to use IPv6.

When set to 0 (default), the component will use IPv4 exclusively. When set to 1, the component will use IPv6 exclusively. When set to 2, the component will listen for both IPv4 and IPv6 connections. If IPv6 is not available on the system, only IPv4 will be used. The default value is 0. Possible values are:

0 IPv4 Only
1 IPv6 Only
2 IPv6 and IPv4

Base Configuration Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the component whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g. RuntimeLicense, License File).
  • License Type: The type of license installed (e.g. Royalty Free, Single Server).
UseDaemonThreads:   Whether threads created by the component are daemon threads.

If set to True (default), when the component creates a thread the thread's Daemon property will be explicitly set to True. When set to False the component will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

By default the component will use the system security libraries to perform cryptographic functions. Setting this to True tells the component to use the internal implementation instead of using the system's security API.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks SFTP 2020 Android Edition - Version 20.0 [Build 8162]