Route via SSH2 Assertion
The Route via SSH2 assertion is used to route SCP and SFTP requests to an external SSH server. This assertion supports SSH2 only; SSH1 is not supported.
The
Route via SSH2
assertion is used to route SCP and SFTP requests to an external SSH server. This assertion supports SSH2 only; SSH1 is not supported.You can add a list of fingerprints and validate the server's host key against multiple fingerprints.
To view or modify the list of enabled ciphers for SSH2 routing, see the
ssh.routingEnabledCiphers
cluster property. To view or modify the list of enabled KEX algorithms for SSH2 routing, see the ssh.routingEnabledKexAlgs
cluster property.How to Perform SFTP Partial Downloads/Uploads
This section is intended for advanced users who are dealing with a specific use case involving SFTP and partial downloads/uploads. This procedure should not be required as part of a normal workflow.
You must apply specific policy configuration if you are downloading or uploading a file from a listen port that has been configured to use partial upload/uploads for SFTP GET/PUT. Ensure the following policy fragment (or equivalent) is present in the SFTP policy:

Details:
Line | Description |
4 | Insert the Configure Message Streaming Assertion. Ensure that the target is "Request" and that "Enable streaming (no buffering)" is selected. |
5 | Insert the Route via SSH2 assertion and configure it as follows: [Connection] Tab
[Authentication] Tab
[Advanced] Tab
|
Using the Assertion
- Do one of the following:
- To add the assertion to the Policy Development window, see Add an Assertion.
- To change the configuration of an existing assertion, proceed to step 2 below.
- When adding the assertion, theSSH2 Routing Propertiesautomatically appear. When modifying the assertion, right-clickRoute via SSH2in the policy window and selectSSH2 Routing Propertiesor double-click the assertion in the policy window. The assertion properties are displayed.
- Configure the properties of the [Connection] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.SettingDescriptionConnection settingsProtocolSelect the protocol to use:SCPorSFTP.Host nameEnter the hostname of the remote server or a context variable that contains the hostname. This name is verified against the X.509 certificate. You may reference context variables.Port numberSpecify the port number or a context variable to use for the security method chosen. This default port number is22. You may reference context variables.Connect timeoutSpecify the number of seconds before the SSH connection times out.Read TimeoutSpecify the SSH read timeout in seconds. This timeout applies to downloads only.Validate Server's Host KeySelect this check box to validate the SSH public key of the server against a list of fingerprints that you will specify using the [Manage Host Key] button. At least one match must be available, else it throws a connection error.This checkbox is selected by default.Clear this check box to not validate the host key of the server.Manage Host KeyThis button is available only when you are validating the server's host key. Use this button to enter the fingerprints against which the host key is validated. You can enter multiple fingerprints, each fingerprint in a new line as shown below:b9:ac:0c:3d:bb:07:a8:a3:cc:eb:d7:f8:c4:89:b1:27b7:ac:0c:3d:bz:07:a8:a5:cc:eb:d7:f2:c4:89:b1:22Complete the following:
- SSH Public Key Fingerprint:Paste the SSH public key fingerprint(s) as retrieved from the remote server's public key location.
- Load From File:Select this to load the fingerprint from a text file.
The fingerprint should be a colon-delimited series of two-digit hexadecimal values; for example:b9:ac:0c:3d:bb:07:a8:a3:cc:eb:d7:f8:c4:89:b1:27. This fingerprint can be determined using thessh-keygencommand on the server:# ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key2048 b9:ac:0c:3d:bb:07:a8:a3:cc:eb:d7:f8:c4:89:b1:27/etc/ssh/ssh_host_rsa_key.pub#When most SSH clients (for example, ssh, PuTTY) first connect to a server, the server's fingerprint are displayed.Use Default KEX AlgorithmsSpecifies that the values are taken from the global cluster property, ssh.routingEnabledKexAlgs.Default:CheckedClear this checkbox to enable theManage Key Exchange Algorithmsbutton, where you can select and order the enabled KEX algorithms.Manage KEX AlgorithmsLists all the supported KEX algorithms. You can search by the KEX algorithm name.You can select and order the KEX algorithms as per your preference. If you are not sure, click theUse Default Listbutton to select the default KEX algorithms and their recommended order.Default:DisabledCommand SettingsCommand TypeChoose the command type from the drop-down list:From VariableUpload To (PUT)Download From (GET)Get Directory Listing (LIST)Get File Attributes (STAT)Delete File (DELETE)Move File (MOVE)Create Directory (MKDIR)Delete Directory (RMDIR)To learn more information about each command type, see the "Description of Command Types" table below.Command Type VariableAlternatively, you can specify a context variable instead of choosing a command type from the drop-down list.Ensure that the content variable resolves to one of the command types listed in "Description of Command Types". Otherwise, the assertion fails.When using an SFTP inbound listener, use a value such as${request.command.type}.Message SourceSelect the source message to upload from the drop-down list:Request, orResponse. This field is available only when you selectUpload Toas theCommand Typein the [Connection] tab.Message TargetSelect the message target from the drop-down list:Request,Response, orMessage Variable. If using a Message Variable, one will be created if it does not already exist.This field is available only when you selectDownload Fromas theCommand Typein the [Connection] tab.Message VariableIf you are targeting the message to a variable, enter the context variable in this field.DirectorySpecify the directory to upload to or download from. The user must have read permission on the directory to download and write permission to upload.The following is an example of a directory for an SFTP inbound listener./my/root/directory${request.ssh.path}When uploading, the specified directory must exist already. This assertion will not create a directory.File nameEnter the name of the file. The user must have read permission to download or write permission to upload.The following is an example of a file name.${request.ssh.file}New File NameEnter the new file name of the file. This option is only applicable to SFTP MOVE.The following is an example of a new file name (all one line):/my/root/dir${request.command.parameter.newPath/${request.command.parameter.newFile}Descriptions of Command TypesSettingDescriptionFrom VariableSelect this option to allow the command type to be determined from the specified context variable. If you select this option, you must specify a valid context variable in the "Command Type Variable" field.Upload to (PUT)Select this option to do the following.- Fail if File ExistsThe upload fails if the file already exists.
- OverwriteDeselect this option if partial file uploads are allowed. If there is an existing file with the same name, the file is overwritten or truncatedbeforethe upload starts.
- File OffsetSpecify the file offset point from which to start writing the file. Default:0
Download from (GET)Select this option to do the following.- File OffsetSpecify the file offset point from which to start retrieving the file data. Default:0
- File LengthSpecify the length of the file data to retrieve. If the EOF ("end of file") is reached, the returned length can be less than the input length.The default is to read the entire file until EOF, which is-1.
Get Directory Listing (LIST)Select this option to retrieve the directory listing of the folder specified. It returns the list in an XML format.Get File Attributes (STAT)Select this option to retrieve the file attributes for the file that is specified, by using the file name and directory. It returns a single file element, or, if the file does not exist, it returns 0.Delete File (DELETE)Select this option to delete the file by specifying the file name and directory.Move File (MOVE)Select this option to move the file or directory to the new location specified. A new file name must be specified, which can either be a relative file name or absolute file path.Create Directory (MKDIR)Select this option to create a directory to the location specified.Delete Directory (RMDIR)Select this option to delete a directory from the location specified. - Select the [Authentication] tab.
- Configure the properties of the [Authentication] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.SettingDescriptionAuthenticationSelect the protocol to use:
- Pass through user name and password credentials in the request: Select this option to use the credentials already present in the request.
- Specify user credentials: Select this option to enter specific credentials in the fields below.
UsernameEnter the user name to connect to the server.PasswordIf you are authenticating using password, select the password from the drop-down list.If the password you require is not listed, click [Manage Stored Passwords] to add it to the password storage of the Gateway. For more information, see Manage Stored Passwords.You cannot type the password directly here. The password must be defined in the secure password storage.Private KeyIf you are authenticating using a private key, select the key to use.If the private key you require is not listed, click [Manage Stored Passwords] to add it to the secure storage area of the Gateway. For more information, see Manage Stored Passwords.Tip:Be sure to selectPEM Private Keyin the "Type" field if you add a private key.Max Retry CountEnter the number of times authentication must be attempted before falsifying the assertion.Default:1If this field is left empty or the context variable that is entered is invalid, it defaults to the global value (ssh.session.authMaxRetryCount) that is set in Input/Output cluster properties. - Select the[Advanced]tab.
- Configure the properties of theAdvanced] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.SettingDescriptionAdvanced Command SettingsContent typeSpecify the MIME Content-Type header. This header only applies to downloads, and the content type is used for files being uploaded to the Gateway.File OffsetEnter a number that represents the point from which to start reading or writing the file. Specifying a number other than "0" allows for partial reads or writes. This option applies for only SFTP GET/PUT.Default:0If the file offset is "0", the file is automatically truncated (emptied) before being written to. For values other than "0", the original file contents are overwritten without truncation.File LengthEnter the length of the file being uploaded, if for SCP PUT. If it is for SFTP GET/PUT enter the length of the file to download or upload.If the file length is -1, the entire input stream is read and stashed to calculate the length, if it is needed. It is only needed for SCP PUT.Default:-1(for the entire file)Set File Size to Context VariableSelect the check box to save the file size to the specified context variable. This only applies to SFTP GET/STAT. Clear this check box if you do not want to save the file size to a context variable. This setting is the default.Preserve File Mode (Permission)Select this check box to preserve the file mode (permission) if available for SFTP.Clear this check box if you do not want to preserve the file mode (permission). This is the default, and means that every user has read and write permission.Initiate SFTP with the "-p" parameter and select thePreserve File Mode (Permission)option. This ensures that the file permissions are preserved. Only the file mode is preserved. Other metadata such as the access modification times are not preserved. This check box is only available for the "SFTP" protocol and copy method "Upload To". It also works only with an SFTP inbound listener.Fail if File ExistsSelect this check box to abort the file upload if the file already exists. Clear this check box to upload and overwirte any existing file. This only applies to SFTP Upload commands.Override maximum message sizeSelect this check box to override the permitted maximum size of the routing message. Clear this check box to use the value set in theio.xmlPartMaxBytescluster property. This check box is available only when you selectDownload Fromas theCommand Typein the [Connection] tab.
- Restrict messages to:Enter the maximum permitted size of the response message, in bytes. You may specify a context variable.
- Allow unlimited message size (not recommended):Select this option to allow response messages of unlimited size.
Current WSS header handling:Specify how to handle the security header. This section is available only when you selectUpload Toas theCommand Typein the [Connection] tab.Don't modify the request Security headerInstructs the Gateway to leave the security header in the outgoing SOAP request message as-is. The security header in the request may still have been modified if the Gateway needed to decrypt any encrypted material during message processing.Use this setting if the protected service must check the original security header in the request. Also use this setting if it does not matter to the protected service whether the request messages have a security header.For best performance, use this setting whenever possible to minimize the amount of per-request message modification.Do not modify the Security header if the policy uses WS-Security.Remove Layer 7 actor and mustUnderstand attributes from processed Security headerInstructs the Gateway to remove the "mustUnderstand" attribute and 'Layer 7' actor from the security header in the outgoing SOAP message.Use this setting if the presence of the Layer 7 actor causes issues with the back-end service. In certain cases, this actor may cause the back-end service to ignore the Security headers because it believes it is addressed to someone else. You will also use this setting if the back-end service does not support Security and will reject a request with "mustUnderstand" asserted on the Security header.An alternative might be to remove the Security header completely. However, doing so incurs a performance penalty because of the extra processing that is required to remove these from the messages. You may want to keep the Security headers intact for logging purposes.Remove processed Security header from request before routingInstructs the Gateway to remove any security header that was processed by the gateway before forwarding the request to the protected service.Use this setting when the protected service is not expecting security headers in the forwarded SOAP requests. - Click [OK] when done.
- Input/Output Cluster Properties (specifically thessh.*properties)