Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Route via SSH2 Assertion

Last update August 24, 2018

The Route via SSH2 assertion secures requests from the CA API Gateway to back-end services, so that SCP and SFTP outbound requests can be made to an external SSH server.

To view or modify the list of enabled ciphers for SSH2 routing, see the ssh.routingEnabledCiphers cluster property.

This assertion supports SSH2 only; SSH1 is not supported.

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

  1. Select SFTP for the protocol.
  2. Enter the Host nameand Port number of the SFTP server.
  3. Select From Variable as the command type and then enter request.command.type as the variable.
  4. Enter ${request.ssh.path} as the directory name.
  5. Enter ${request.ssh.file} as the file name.
  6. Enter ${request.command.parameter.newPath}/${request.command.parameter.newFile} as the new file name.

[Authentication] Tab

Specify the credentials for the SFTP server.

[Advanced] Tab

  1. Select the Set File Size to Context Variable check box and enter ssh.file.size as the context variable.
  2. Select the Override maximum message size check box and select [Allow unlimited message size].
  3. Enter the following context variables in these fields:
    • File Offset: ${request.command.parameter.offset}
    • File Length: ${request.command.parameter.length}

Using the Assertion

  1. 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.
  2. When adding the assertion, the SSH2 Routing Properties automatically appear. When modifying the assertion, right-click Route via SSH2 in the policy window and select SSH2 Routing Properties or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the properties of the [Connection] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.

    Setting Description
    Connection settings
    Protocol Select the protocol to use: SCP or SFTP.
    Host name Enter 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 number Specify the port number or a context variable to use for the security method chosen. This default port number is 22. You may reference context variables.
    Connect timeout Specify the number of seconds before the SSH connection times out.
    Read Timeout Specify the SSH read timeout in seconds. This timeout applies to downloads only.
    Validate Server's Host Key

    Select this check box to validate the SSH public key of the server against a fingerprint that you will specify using the [Manage Host Key] button. This setting is the default.

    Clear this check box to not validate the host key of the server.

    Manage Host Key

    This button is available only when you are validating the server's host key. Use this button to enter the fingerprint against which the host key is validated. Complete the following:

    • SSH Public Key Fingerprint: Paste the SSH public key fingerprint as retrieved from the remote server's public key location.
    • Load From File: Select this to load the fingerprint from a text file.

    About Host Key Fingerprints

    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 the ssh-keygen command on the server:

    # ssh-keygen -l -f
    /etc/ssh/ssh_host_rsa_key
    2048 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.
    Command Selection
    Command Type

    Choose the command type from the drop-down list:

    From Variable
    Upload 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 Variable

    Alternatively, 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.

    Tip: When using an SFTP inbound listener, use a value such as ${request.command.type}.

    Message Source Select the source message to upload from the drop-down list: Request, or Response. This field is available only when you select Upload To as the Command Type in the [Connection] tab.
    Message Target Select the message target from the drop-down list: Request, Response, or Message Variable. If using a Message Variable, one will be created if it does not already exist.
    This field is available only when you select Download From as the Command Type in the [Connection] tab.
    Message Variable If you are targeting the message to a variable, enter the context variable in this field.
    Directory

    Specify 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}

    Note: When uploading, the specified directory must exist already. This assertion will not create a directory.

    File name

    Enter 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 Name

    Enter 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 Types

    Setting Description
    From Variable Select 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 Exists
      The upload fails if the file already exists.
    • Overwrite
      Deselect this option if partial file uploads are allowed. If there is an existing file with the same name, the file is overwritten or truncated before the upload starts.
    • File Offset
      Specify the file offset point from which to start writing the file. Default: 0
    Download from (GET)

    Select this option to do the following.

    • File Offset
      Specify the file offset point from which to start retrieving the file data. Default: 0
    • File Length

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

     

  4. Select the [Authentication] tab.
  5. Configure the properties of the [Authentication] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.

    Setting Description
    Authentication

    Select 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.
    Username Enter the user name to connect to the server.
    Password

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

    Tip: You cannot type the password directly here. The password must be defined in the secure password storage.

    Private Key

    If 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 select PEM Private Key in the "Type" field if you add a private key. 

     

  6. Select the [Advanced] tab.

  7.  Configure the properties of the [Advanced] tab as follows. If you are unsure of the settings to use, consult with the SSH server administrator.

    Setting Description
    Advanced Command Settings
    Content type Specify 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 Offset

    Enter 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: 0

    Note: If 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 Length

    Enter 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 Variable Select 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.

    Note: Initiate SFTP with the "-p" parameter and select the Preserve 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 Exists Select 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 size

    Select this check box to override the permitted maximum size of the routing message. Clear this check box to use the value set in the io.xmlPartMaxBytes cluster property. This check box is available only when you select Download From as the Command Type in 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 select Upload To as the Command Type in the [Connection] tab.
    Don't modify the request Security header

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

    Note: Do not modify the Security header if the policy uses WS-Security.

    Remove Layer 7 actor and mustUnderstand attributes from processed Security header

    Instructs 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 routing

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

  8. Click [OK] when done.


More Information


Was this helpful?

Please log in to post comments.