Layer7 API Gateway 10.0

PDF
index 10.0 congw.10.0 9.4 9.3 9.2 9.1 9.0
Japanese English

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:
  Route_via_SSH2_sample_policy.bmp  
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 name 
     
    and 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
 
  1. 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 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 Key
     
    This 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:27
    b7:ac:0c:3d:bz:07:a8:a5:cc:eb:d7:f2:c4:89:b1:22
    Complete 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 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.
     
    Use Default KEX Algorithms
     
    Specifies that the values are taken from the global cluster property, ssh.routingEnabledKexAlgs.
     
    Default:
     Checked
    Clear this checkbox to enable the 
    Manage Key Exchange Algorithms
     button, where you can select and order the enabled KEX algorithms.
     
    Manage KEX Algorithms
     
    Lists 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 the 
    Use Default List
     button to select the default KEX algorithms and their recommended order.
     
    Default:
     Disabled
     
    Command Settings
     
     
    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.
     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}
     
     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.
     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. 
     
    Max Retry Count
     
    Enter the number of times authentication must be attempted before falsifying the assertion.
     
    Default:
     1
    If 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.
     
  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
     
     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.
     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.
     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.