Using the Balabit Shell Control Box REST API

Copyright © 2017 Balabit SA. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balabit.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (https://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

This product uses Botan cryptographic library. The library was released under the BSD-2 license. For details about the Botan license, see Botan cryptographic library license.

The Balabit™ name and the Balabit™ logo are registered trademarks of Balabit SA.

The Balabit Shell Control Box™ name and the Balabit Shell Control Box™ logo are registered trademarks of Balabit.

Citrix®, ICA® and XenApp™ are trademarks or registered trademarks of Citrix Systems, Inc.

Linux™ is a registered trademark of Linus Torvalds.

Sun™, Sun Microsystems™, the Sun logo, Sun Fire 4140™, Sun Fire 2100™, Sun Fire 2200™, Sun Fire 4540™, and Sun StorageTek™ are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries.

The syslog-ng™ name and the syslog-ng™ logo are registered trademarks of Balabit.

VMware™, VMware ESX™ and VMware View™ are trademarks or registered trademarks of VMware, Inc. and/or its affiliates.

Windows™ 95, 98, ME, 2000, XP, Server 2003, Vista, Server 2008, 7, 8, and Server 2012 are registered trademarks of Microsoft Corporation.

The Zorp™ name and the Zorp™ logo are registered trademarks of BalaSys IT Ltd.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER. Balabit is not responsible for any third-party websites mentioned in this document. Balabit does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balabit will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

Botan cryptographic library license. 

Botan http://botan.randombit.net/ is distributed under these terms:

Copyright ©

  • 1999-2013,2014 Jack Lloyd

  • 2001 Peter J Jones

  • 2004-2007 Justin Karneges

  • 2004 Vaclav Ovsik

  • 2005 Matthew Gregan

  • 2005-2006 Matt Johnston

  • 2006 Luca Piccarreta

  • 2007 Yves Jerschow

  • 2007-2008 FlexSecure GmbH

  • 2007-2008 Technische Universitat Darmstadt

  • 2007-2008 Falko Strenzke

  • 2007-2008 Martin Doering

  • 2007 Manuel Hartl

  • 2007 Christoph Ludwig

  • 2007 Patrick Sona

  • 2010 Olivier de Gaalon

  • 2012 Vojtech Kral

  • 2012-2014 Markus Wanner

  • 2013 Joel Low

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

April 03, 2017


Table of Contents

1. Introduction
1.1. Message format
1.2. How to configure SCB using REST
1.3. How to configure SCB using REST — a sample transaction
2. Using the SCB REST API
2.1. Authenticate to the SCB REST API
2.2. Checking the transaction status
2.3. Open a transaction
2.4. Commit a transaction
2.5. Delete a transaction
2.6. Reviewing the changelog of a transaction
2.7. Application level error codes
2.8. Navigating the configuration of SCB
2.9. Modifying the configuration of SCB
2.9.1. Delete an object
2.9.2. Create a new object
2.9.3. Change an object
3. Basic settings
3.1. Retrieve basic firmware and host information
3.2. Network settings
3.2.1. Web interface
3.2.2. Network configuration options
3.2.3. DNS servers
3.2.4. Routing between interfaces
3.2.5. Naming options
3.2.6. Network addresses
3.2.7. Routing table
3.2.8. Local services of SCB
3.2.9. Local services — Web login for administrators
3.2.10. Local services — Web login for users
3.3. Date and time
3.3.1. Date & time
3.3.2. NTP servers
3.3.3. Timezone
3.4. Logs, monitoring and alerts
3.4.1. Management options
3.4.2. Syslog server settings
3.4.3. Disk fill-up prevention
3.4.4. Mail settings
3.4.5. Health monitoring
3.4.6. SNMP settings
3.4.7. SNMP traps
3.4.8. Local services — access for SNMP agents
3.4.9. Alerting
3.4.10. System alerts
3.4.11. Traffic alerts
4. User management and access control
4.1. User management and access control
4.2. Authentication and user database settings
4.3. Privileges of usergroups
4.4. Manage users and usergroups locally on SCB
4.5. Manage usergroups locally on SCB
4.6. Manage users locally on SCB
5. Managing SCB
5.1. Troubleshooting options
5.2. Internal certificates
5.3. Passwords stored on SCB
5.4. Private keys stored on SCB
5.5. Certificates stored on SCB
5.6. Local services — enabling SSH access to the SCB host
5.7. RPC API
6. General connection settings
6.1. Channel policy
6.2. Policies
6.3. Audit policies
6.4. Real-time content monitoring with Content Policies
6.5. LDAP servers
6.6. Signing CA policies
6.7. Time policy
6.8. Trusted Certificate Authorities
6.9. Local user databases
6.10. User lists
7. HTTP connections
7.1. HTTP connections
7.2. Global HTTP options
7.3. HTTP settings policies
8. Citrix ICA connections
8.1. ICA connections
8.2. Global ICA options
8.3. ICA settings policies
9. RDP connections
9.1. RDP connections
9.2. RDP channels
9.3. Configuring domain membership
9.4. Global RDP options
9.5. RDP settings policies
10. SSH connections
10.1. SSH connections
10.2. SSH connection policies
10.3. SSH channels
10.4. SSH authentication policies
10.5. Global SSH options
10.6. SSH settings policies
10.7. SSH host keys and certificates
11. Telnet connections
11.1. Telnet connections
11.2. Global Telnet options
12. VNC connections
12.1. VNC connections
12.2. Global VNC options
13. Searching and indexing sessions
13.1. Auditing connections
13.2. Searching in the connection database
13.3. Local services — configuring the indexer
13.4. Indexer policies
14. Reporting
14.1. Reporting
14.2. Reports
14.3. Built-in subchapters
14.4. Pre-defined reports
14.5. Content subchapters
14.6. Custom subchapters
14.7. Connection statistics subchapters
15. Advanced authentication and authorization
15.1. Usermapping policy
15.2. Plugins
15.3. Authentication and authorization plugins
15.4. Credential store plugins
15.5. Credential stores
15.6. Ticketing policies
15.7. Ticketing plugins
List of SCB REST API parameters and elements

List of Examples

2.1. Authenticate to the SCB REST server using curl

List of Procedures

1.2. How to configure SCB using REST
1.3. How to configure SCB using REST — a sample transaction

Chapter 1. Introduction

Starting with Balabit Shell Control Box version 4 F2, certain parts and features of SCB can be configured using a RESTful API (Representational State Transfer Application Programming Interface). The REST server conforms to the Hypermedia as the Engine of Application State (HATEOAS).

The SCB REST API uses JSON over HTTPS. The REST server has a single entry point and all resources are available at paths (URLs) returned in the response for a request sent to the entry point. The only path that is guaranteed not to change is /api/authentication. Every other path should be reached by navigating the links returned.

The SCB REST API allows you to create, read, update and delete (CRUD) the configuration resources of SCB.

In this tutorial, all examples are displayed with curl, but you can use any other HTTP client. In the examples it is assumed that the REST server is listening on the default HTTP port of SCB (443).

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

1.1. Message format

Response headers

The following headers are included in every response. Other headers are specific to responses to specific requests.

  • Allow: The SCB REST API allows you to create, read, update and delete (CRUD) the configuration resources of SCB. The value of the header lists the available actions for the resource or object.

  • Content-Language: The language of the response. Currently only English (en) is supported.

  • Content-Type: All messages are JavaScript Object Notation (JSON) objects. The SCB REST server sends all REST API responses in application/json format.

Response body

The response body contains JSON objects. These objects always contains a meta field with links to different parts of the REST service. The keys in the response, which are not resource identifiers, start with the underscore (_) charater, for example, meta, key, and error. In most cases, the following entries can be found in the meta object.

Element Type Description Notes
meta     Top level element, contains links to different parts of the REST service  
  changes string Path to the transaction changelog. This value is always /api/transaction/changes. For details, see Section 2.6, Reviewing the changelog of a transaction.
  href string (relative path) Path of the resource that returned the response. When creating a new object, this is the URL of the created object. For example, /api/authentication
  parent string (relative path)    
  next string (relative path) Path of the next sibling of the current resource For example, /api/configuration
  prev string (relative path) Path of the previous sibling of the current resource  
  first string (relative path) Path of the first sibling of the current resource  
  last string (relative path) Path of the last sibling of the current resource  
  transaction string (/api/transaction) The endpoint of the transaction log For details on how SCB handles transactions, see Procedure 1.2, How to configure SCB using REST.
items   list of JSON objects List of endpoints (objects) available from the current endpoint.

Each object in the list contains a key and a meta object for the endpoint. For example:

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-rsa-10.10.100.1:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22"
      }
    },
    {
      "key": "ssh-rsa-10.10.20.35:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22"
      }
    },
    {
      "key": "ssh-rsa-10.40.0.28:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.40.0.28:22"
      }
    }
  ]
}

For example:

{
  "meta": {
    "href": "/api/authentication",
    "next": "/api/configuration"
  }
}

Error responses

All error responses are JSON objects with the following keys.

  • meta: JSON object containing navigation links. For details, see Section 1.1, Message format.

  • error: JSON object containing information about the error.

Element Type Description Notes
error     Top level element, contains links to different parts of the REST service  
  type string The type of the error that occurred. For example, AuthenticationFailure, or NodeNotFound. For a complete list, see Section 2.7, Application level error codes.
  message string A text message that describes the error. For example, Unable to locate the requested path.
  details JSON object List of additional information about the error (for example the path where the error occurred).

For example:

"details": {
  "path": "no/such/path"
}

The following is a complete error response.

{
  "error": {
    "type": "NodeNotFound",
    "message": "Unable to locate the requested path",
    "details": {
      "path": "no/such/path"
    }
  },
  "meta": {
    "href": "/api/configuration/no/such/path",
    "parent": "/api/configuration"
  }
}

1.2. Procedure – How to configure SCB using REST

The SCB REST server uses a transactional model for configuration management. Modifying the configuration has the following main steps. The steps are explained in detail in later sections of the tutorial. You find a simple transaction with detailed requests and responses in Procedure 1.3, How to configure SCB using REST — a sample transaction.

  1. Authenticate on the SCB REST server, and receive a session_id. For details, see Section 2.1, Authenticate to the SCB REST API.

  2. Open a transaction. This transaction will collect the changes and modifications you do, compared to the SCB configuration that is active at the time of opening the transaction. It is similar to a shopping cart, where your modifications are the items in the cart. For details, see Section 2.3, Open a transaction.

    Note that opening a transaction locks the configuration of SCB similarly to accessing SCB from the web interface. For details, see Section 4.2.2, Multiple users and locking in The Balabit Shell Control Box 4 F4 Administrator Guide.

  3. Change and modify the configuration of SCB as you need. Note that to modify the configuration, you must have the required privileges. For details, see Section 5.7, Managing user rights and usergroups in The Balabit Shell Control Box 4 F4 Administrator Guide. For details on navigating and modifying the configuration of SCB, see Section 2.8, Navigating the configuration of SCB and Section 2.9, Modifying the configuration of SCB

  4. Commit your transaction to submit your changes to SCB (this is similar to clicking Checkout in a web shop). For details, see Section 2.4, Commit a transaction.

    If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

    If you do not want to commit your changes, and would like to restart with the original configuration of SCB, you can simply delete the transaction. This is similar to the rollback transaction in SQL. If your session times out, your transaction is deleted automatically. For details, see Section 2.5, Delete a transaction.

  5. SCB checks and validates the changes in your transaction. If other users have changed the configuration of SCB since you opened the transaction, SCB tries to merge your changes to the current configuration.

  6. If your changes are valid, SCB applies them and you have successfully changed the configuration of SCB. Otherwise, the REST server returns an error response.

1.3. Procedure – How to configure SCB using REST — a sample transaction

This procedure shows a sample transaction with detailed requests and responses. For details on the transaction model, see Procedure 1.2, How to configure SCB using REST.

  1. Authenticate on the SCB REST server, and receive a session_id.

    curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/authentication",
        "next": "/api",
        "transaction": "/api/transaction"
      }
    }
    --- END RESPONSE BODY ---
  2. Open a transaction.

    curl --data "" --cookie session_id=<session_cookie> --insecure -X POST https://<IP-address-of-SCB>/api/transaction
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/transaction",
        "parent": "/api"
      }
    }
    --- END RESPONSE BODY ---
  3. Retrieve a resource. The following example shows the resource corresponding to the AAA > Settings page of the SCB web interface.

    curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration/aaa/settings
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "key": "settings",
      "meta": {
        "first": "/api/configuration/aaa/settings",
        "href": "/api/configuration/aaa/settings",
        "last": "/api/configuration/aaa/settings",
        "next": null,
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
      },
      "settings": {
        "backend": {
          "cracklib_enabled": false,
          "expiration_days": 0,
          "minimum_password_strength": "good",
          "remember_previous_passwords": 10,
          "selection": "local"
        },
        "method": {
          "selection": "passwd"
        },
        "require_commitlog": false
      }
    }
    --- END RESPONSE BODY ---
  4. Change and modify the configuration of SCB as you need. The following example configures SCB to check the password strength of the passwords for users of the SCB web interface.

    # Body of the PUT request. You can read it from a file, for example, body.json
    {
      "backend": {
    	"cracklib_enabled": true,
    	"expiration_days": 0,
    	"minimum_password_strength": "good",
    	"remember_previous_passwords": 10,
    	"selection": "local"
      },
      "method": {
    	"selection": "passwd"
      },
      "require_commitlog": false
      }
    # Command to use
    curl -d @body.json --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration/aaa/settings
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "first": "/api/configuration/aaa/settings",
        "href": "/api/configuration/aaa/settings",
        "last": "/api/configuration/aaa/settings",
        "next": null,
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
      }
    }
    --- END RESPONSE BODY ---
  5. Commit your transaction to submit your changes to SCB.

    curl -d '{"status": "commit","message": "My commit message"}' --cookie session_id=<session_cookie> --insecure -X PUT https://<IP-address-of-SCB>/api/transaction
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/transaction",
        "parent": "/api"
      }
    }
    --- END RESPONSE BODY ---

    If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

  6. If your changes are valid, SCB applies them and you have successfully changed the configuration of SCB. Otherwise, the REST server returns an error response.

Chapter 2. Using the SCB REST API

2.1. Authenticate to the SCB REST API

Prerequisites: 

  • You can access the REST server on the same IP address and port that you use to access the SCB web interface. Note that management (administrator) access must be enabled on the interface. For details on configuring management access, see Procedure 4.3.1, Configuring user and administrator login addresses in The Balabit Shell Control Box 4 F4 Administrator Guide.

  • The user accessing the SCB REST API must have the REST server privilege. For details, see Procedure 5.7.2, Modifying group privileges in The Balabit Shell Control Box 4 F4 Administrator Guide. Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of SCB.

The authentication procedure: 

  1. To authenticate on the SCB REST server, send an HTTP GET request using the basic HTTP authentication method, including your username and password to the /api/authentication resource.

  2. If the authentication is successful, the server returns the 200 status code, and a meta object in the response body. Also, the HTTP headers of the response includes an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request.

  3. For every subsequent request, include the session_id header with the value of the received session ID. For example:

    session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
  4. The authenticated session times out after 20 minutes of inactivity.

URL

GET https:<IP-address-of-SCB>/api/authentication

Headers

Header name Description Required Values
Authorization Contains the username and password of the user Required The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ==

Sample request

Example 2.1. Authenticate to the SCB REST server using curl

The following command authenticates on SCB using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SCB. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SCB. For details, see the curl man page).

When using the REST API in production environments, make sure to download the CA certificate of SCB from Basic Settings > Management > SSL certificate > CA X.509 certificate, and validate the certificate of SCB using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SCB.

curl --basic --digest --user <username>:<password> --cookie-jar cookies --insecure https://<SCB-IP-address>/api/authentication

The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

The following command retrieves the configuration of SCB, using the session ID received during the authentication.

curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration

Response

The following is a sample response received if the authentication is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
     "href": "/api/authentication",
     "next": "/api",
     "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Successful authentication
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the GET method for authentication.

2.2. Checking the transaction status

Before changing anything in the configuration of SCB, you must POST a request to open a transaction.

URL

GET https:<IP-address-of-SCB>/api/transaction/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command retrieves the transaction status of SCB, using the session ID received during the authentication.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "key": "transaction",
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "transaction": {
    "status": "closed"
  }
}
Element Type Description
transaction     Top level element, contains the details of the current transaction
  status string The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Transaction status has been retrieved successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.

2.3. Open a transaction

Before changing anything in the configuration of SCB, you must POST a request to open a transaction. For details about the transaction model of SCB see Procedure 1.2, How to configure SCB using REST.

Note that opening a transaction locks the configuration of SCB similarly to accessing SCB from the web interface. For details, see Section 4.2.2, Multiple users and locking in The Balabit Shell Control Box 4 F4 Administrator Guide.

URL

POST https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

POST body

Note that you must send a body (which can be empty) in this POST request, or a Content-Length: 0 header. Otherwise the SCB REST server returns a 411 - Length Required error.

Sample request

The following command opens a new transaction on SCB, using the session ID received during the authentication.

curl -X POST --data "" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

After opening a transaction successfully, the transaction status changes to open.

{
    "body": {
        "status": "open"
    },
    "key": "transaction",
    "meta": {
        "changes": "/api/transaction/changes",
        "href": "/api/transaction",
        "parent": "/api"
    }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Transaction opened successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the POST method to open a transaction.
409 WebGuiOrRpcApiConfigInProgress The configuration of SCB is locked. Opening a new transaction is not allowed while another user is modifying configuration through other interfaces than the REST API. For example, web GUI, console, and so on.
411 UnsupportedMethod You must send a body (which can be empty) in this POST request, otherwise the SCB REST server returns a 411 - Length Required error.

2.4. Commit a transaction

To submit your changes to SCB, you have to commit the transaction by using a PUT request with a JSON object. For details about the transaction model of SCB see Procedure 1.2, How to configure SCB using REST.

URL

PUT https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

PUT body

The PUT request must include the following JSON object in its body.

{
  "status": "commit"
}

If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

{
  "status": "commit",
  "message": "My commit message"
}

Sample request

The following command commits a transaction to SCB, using the session ID received during the authentication.

curl -d '{"status": "commit","message": "My commit message"}' --cookie session_id=<session_cookie> -X PUT https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if committing the transaction is successful. For details of the meta object, see Section 1.1, Message format.

After a successful commit, the transaction status changes to closed. To make other changes, you have to open a new transaction.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "key": "transaction",
  "transaction": {
    "status": "closed"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Transaction committed successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the PUT method to commit a transaction.

2.5. Delete a transaction

To delete your changes, you have to delete the transaction. This is similar to the rollback transaction in SQL. For details about the transaction model of SCB see Procedure 1.2, How to configure SCB using REST. Deleting the transaction also deletes the configuration lock of SCB.

URL

DELETE https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command deletes a transaction, reverting the configuration to the state it was when the transaction was opened, or to the current configuration available on SCB (if it another user has modified it since you opened the transaction).

curl --cookie session_id=<session_cookie> -X DELETE https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if deleting the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Transaction deleted successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the DELETE method to reset a transaction.

2.6. Reviewing the changelog of a transaction

To review your changes, retrieve the changelog of the transaction. For details about the transaction model of SCB see Procedure 1.2, How to configure SCB using REST.

URL

GET https:<IP-address-of-SCB>/api/transaction/changes

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command retrieves the changelog of the transaction.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction/changes

Response

The response contains the list of changes performed in the transaction, as list of JSON objects. Every change has a type and a path, other elements depend on the type of the transaction. For example, when you delete an object, the changelog includes the deleted object in the old_value field.

Element Type Description
new_order list The new order of a list after the change. This field is available for reorder transactions.
new_value string or JSON object The value of the object after the change. For example, the new value of a parameter.
old_order string or JSON object The order of a list before the change. This field is available for reorder transactions.
old_value string or JSON object The value of the object before the change. For example, the value of a deleted object.
path string Path of the changed endpoint or object.
type string The type of the change. One of: create, delete, reorder, replace

The following is a sample response received if the changelog is empty.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": []
}

The following is a sample changelog received after deleting a Channel policy.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": [
    {
      "old_value": {
        "name": "deny",
        "rules": []
      },
      "path": "/api/configuration/ssh/channel_policies/94615110156697e93121f3",
      "type": "delete"
    }
  ]
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Transaction changelog has been retrieved successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the GET method to retrieve the changelog a transaction.

2.7. Application level error codes

In addition to the standard HTTP status codes, in certain cases, the SCB REST server provides additional information in the response about the error. The following table contains a brief description of such errors. For more details, see the error object in the response body.

Code Description Notes
400 InvalidRequestBody The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value.
400 ConfigTreeNotAvailable An error occurred while preparing the configuration tree for the REST API.
400 SyntacticError A value to be set is not accepted syntactically. Thedetails section contains the path that was found to be invalid.
400 InvalidPath The path provided by the client contains a syntax error. Path components are restricted to contain only lowercase alphanumeric characters, the dash (-) and the underscore (_) character. The details section contains the path that was attempted to be accessed, but could not be retrieved.
400 SemanticError The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
401 Unauthorized The requested resource cannot be retrieved because the client is not authorized to access it. The detailssection contains the path that was attempted to be accessed, but could not be retrieved.
404 NodeNotFound The requested endpoint does not exist in the configuration. The details section contains the path that you tried to access, but could not be retrieved.
404 NodeNotAvailable The requested endpoint exists in the configuration, however, it is not available directly. The details section contains the path that you tried to access, but could not be retrieved.
405 UnsupportedMethod The requested resource does not support the given method. The details section contains the attempted method.
405 PutNotAllowed Replacing the specified path is not supported.
405 MethodNotAllowed An attempt was made to change a configuration subtree in an unsupported way.
405 PostNotAllowed Posting to the specified path is not supported.
405 GetNotAllowed Querying the specified path is not supported.
405 DeleteNotAllowed Deleting the specified path is not supported.
409 MidAirCollisionSemanticError This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would interfere semantically with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 WebGuiOrRpcApiConfigInProgress The configuration of SCB is locked. Opening a new transaction is not allowed while another user is modifying configuration through other interfaces than the REST API. For example, web GUI, console, and so on.
409 MidAirCollision This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would overwrite or interfere with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 NoTransaction An attempt was made to change the configuration when no transaction was open.
409 DoubleTransaction This error is returned when the client attempts to open a transaction while another transaction of that client is already started.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

500 CommitMessageMissing This error is returned when a commit message is required for committing a transaction, but it was not provided in the commit request.
500 TransactionCommitError Unexpected internal errors during committing a transaction are interpreted as TransactionCommitError.
500 AuthorizationError The request could not be authorized due to an unexpected internal error.

2.8. Navigating the configuration of SCB

The main starting point of navigating the SCB configuration using REST is the https:<IP-address-of-SCB>/api/configuration endpoint. If you query this endpoint, the response contains a list of other endpoints that you can follow to list the various resources of SCB, or to list the objects of a specific resource. For example, https:<IP-address-of-SCB>/api/configuration/rdp lists resources related to controlling the Remote Desktop (RDP) protocol, while https:<IP-address-of-SCB>/api/configuration/rdp/channel_policies lists the available RDP Channel Policies.

Note that when you want to create an object that references another object (for example, a Channel Policy that uses a Content Policy), then the referenced object (in this case, the Content Policy) must already exist. For details, see Section 2.9.2, Create a new object.

To modify or delete an object, you need the ID of the object. For details, see Section 2.9.3, Change an object and Section 2.9.1, Delete an object.

The following is a sample command to query the https:<IP-address-of-SCB>/api/configuration endpoint, and a sample response.

curl --cookie session_id=<session_cookie> https:<IP-address-of-SCB>/api/configuration

Response status: 200
--- BEGIN RESPONSE BODY ---
{
  "meta": {
    "first": "/api/configuration",
    "href": "/api/configuration",
    "last": "/api/configuration",
    "next": null,
    "parent": null,
    "previous": null,
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "aaa",
      "meta": {
        "href": "/api/configuration/aaa"
      }
    },
    {
      "key": "alerting",
      "meta": {
        "href": "/api/configuration/alerting"
      }
    },
    {
      "key": "datetime",
      "meta": {
        "href": "/api/configuration/datetime"
      }
    },
    {
      "key": "http",
      "meta": {
        "href": "/api/configuration/http"
      }
    },
    {
      "key": "ica",
      "meta": {
        "href": "/api/configuration/ica"
      }
    },
    {
      "key": "local_services",
      "meta": {
        "href": "/api/configuration/local_services"
      }
    },
    {
      "key": "management",
      "meta": {
        "href": "/api/configuration/management"
      }
    },
    {
      "key": "network",
      "meta": {
        "href": "/api/configuration/network"
      }
    },
    {
      "key": "passwords",
      "meta": {
        "href": "/api/configuration/passwords"
      }
    },
    {
      "key": "plugins",
      "meta": {
        "href": "/api/configuration/plugins"
      }
    },
    {
      "key": "policies",
      "meta": {
        "href": "/api/configuration/policies"
      }
    },
    {
      "key": "private_keys",
      "meta": {
        "href": "/api/configuration/private_keys"
      }
    },
    {
      "key": "rdp",
      "meta": {
        "href": "/api/configuration/rdp"
      }
    },
    {
      "key": "reporting",
      "meta": {
        "href": "/api/configuration/reporting"
      }
    },
    {
      "key": "ssh",
      "meta": {
        "href": "/api/configuration/ssh"
      }
    },
    {
      "key": "telnet",
      "meta": {
        "href": "/api/configuration/telnet"
      }
    },
    {
      "key": "troubleshooting",
      "meta": {
        "href": "/api/configuration/troubleshooting"
      }
    },
    {
      "key": "vnc",
      "meta": {
        "href": "/api/configuration/vnc"
      }
    },
    {
      "key": "x509",
      "meta": {
        "href": "/api/configuration/x509"
      }
    }
  ]
}
--- END RESPONSE BODY ---

2.9. Modifying the configuration of SCB

2.9.1. Delete an object

To delete a configuration object (for example, a policy), use a DELETE request with the ID of the object as the key.

  • You cannot delete policies or objects that are used in other policies (for example, you cannot delete a Time policy that is used in a Channel policy).

  • You cannot delete built-in policies that are available on SCB by default.

  • You must commit your changes to take effect. For details, see Section 2.4, Commit a transaction.

URL

DELETE https:<IP-address-of-SCB>/api/configuration/<endpoint>/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command deletes an RDP Channel policy.

curl --cookie session_id=<session_cookie> -X DELETE -https:<IP-address-of-SCB>/api/configuration/rdp/channel_policies/<object-id>

Response

The following is a sample response received.

{
  "meta": {
    "first": "/api/configuration/rdp/channel_policies/-20100",
    "href": "/api/configuration/rdp/channel_policies/<id-of-the-deleted-object>",
    "last": "/api/configuration/rdp/channel_policies/<id-of-the-deleted-object>",
    "next": null,
    "parent": "/api/configuration/rdp/channel_policies",
    "previous": "/api/configuration/rdp/channel_policies/655555",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK The resource was successfully deleted
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 2.3, Open a transaction.

2.9.2. Create a new object

To create a new object (for example, a new policy), you have to complete the following steps.

  1. Authenticate and open a transaction.

  2. Post the new object as a JSON object to the appropriate resource URL.

  3. If successful, the REST server creates a ID for the new object, and returns it in the key field of the response.

  4. Commit the transaction.

Note that you cannot simply use the JSON from the response of a similar object. If the object contains references to other resources (for example, a Channel policy references a Time policy), then the JSON object contains an embedded _meta object. To get a valid JSON that you can use, you have to replace this embedded object with the ID (_key) of the referenced object. For example, the following is a reference to a Time policy:

"time_policy": {
		"_key": "-100",
		"_meta": {
			"href": "/api/configuration/policies/time_policies/-100"
		}
	}

In a POST or PUT request, you have to change it to the following:

"time_policy": "-100",

URL

POST https:<IP-address-of-SCB>/api/configuration/<path-to-the-parent-resource>

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command creates a new RDP Channel policy. The data content of the request is read from the file body.json

curl -H "Content-Type: application/json" -d @body.json --cookie session_id=1aca4793549c6f22aecd98bc1047d1bf32dd76ef -X POST https://<object-id>/api/configuration/rdp/channel_policies/

For a simple RDP Channel policy that uses the default settings and allows only the Drawing channel, the JSON object is the following.

{
  "name": "drawing-only",
  "rules": [
    {
      "actions": {
        "audit": true,
        "content_policy": null,
        "four_eyes": false,
        "ids": false
      },
      "allowed_for": {
        "clients": [],
        "gateway_groups": [],
        "remote_groups": [],
        "servers": [],
        "time_policy": "-100"
      },
      "channel": "#drawing"
    }
  ]
}

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "key": "f79bcc85-bb8b-4fa5-a141-eb4cf2b6ef33",
  "meta": {
    "href": "/api/configuration/rdp/channel_policies/f79bcc85-bb8b-4fa5-a141-eb4cf2b6ef33",
    "parent": "/api/configuration/rdp/channel_policies",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
201 Created The new resource was successfully created
400 Bad Request The request body format is invalid. The data is not a properly formated JSON object.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 2.3, Open a transaction.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

2.9.3. Change an object

To modify or update an object, use a PUT request on the object you want to change. In the body of the request, you have to upload the entire object, not only the parameter that you want to change.

Note that you cannot simply use the JSON from the response of a similar object. If the object contains references to other resources (for example, a Channel policy references a Time policy), then the JSON object contains an embedded _meta object. To get a valid JSON that you can use, you have to replace this embedded object with the ID (_key) of the referenced object. For example, the following is a reference to a Time policy:

"time_policy": {
		"_key": "-100",
		"_meta": {
			"href": "/api/configuration/policies/time_policies/-100"
		}
	}

In a POST or PUT request, you have to change it to the following:

"time_policy": "-100",

URL

PUT https:<IP-address-of-SCB>/api/configuration/<path-to-the-parent-resource>/<id-of-the-object-to-modify>

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command updates an RDP Channel policy. The data content of the request is read from the file body.json

curl -H "Content-Type: application/json" -d @body.json --cookie session_id=07640a0bf14cdd361d8f5ae2b0b482a786c7a604 -X PUT https://10.40.255.17/api/configuration/rdp/channe_policies/<id-of-the-object-to-modify>

For a simple RDP Channel policy that uses the default settings and allows only the Drawing channel, the JSON object is the following.

{
  "name": "drawing-only",
  "rules": [
    {
      "actions": {
        "audit": true,
        "content_policy": null,
        "four_eyes": false,
        "ids": false
      },
      "allowed_for": {
        "clients": [],
        "gateway_groups": [],
        "remote_groups": [],
        "servers": [],
        "time_policy": "-100"
      },
      "channel": "#drawing"
    }
  ]
}

Response

The following is a sample response received. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/rdp/channel_policies/-20100",
    "href": "/api/configuration/rdp/channel_policies/<id-of-the-modified-object>",
    "last": "/api/configuration/rdp/channel_policies/<id-of-the-modified-object>",
    "next": null,
    "parent": "/api/configuration/rdp/channel_policies",
    "previous": "/api/configuration/rdp/channel_policies/655555",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 Bad Request The request body format is invalid. The data is not a properly formated JSON object.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 2.3, Open a transaction.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

Chapter 3. Basic settings

3.1. Retrieve basic firmware and host information

The /api/info endpoint contains generic information about the SCB host. Note that part of this information is available without authentication.

URL

GET https://<IP-address-of-SCB>/api/info

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command displays the information about SCB that is available without authentication.

curl https://10.40.255.171/api/info

The following command displays the information about SCB that is available for authenticated users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/info

Response

The following is a sample response received by an anonymous user. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "domainname": "balabit",
        "hostname": "scbwriter",
        "nickname": null,
        "support_link": "mailto:scb-administrator@example.com"
    },
    "key": "about_info",
    "meta": {
        "href": "/api/info",
        "parent": "/api"
    }
}

The following is a sample response received by an authenticated user.

{
    "body": {
        "build_date": "2016-09-23",
        "domainname": "balabit",
        "firmware_version": "4.3.2a",
        "hostname": "scbwriter",
        "nickname": null,
        "support_link": "mailto:scb-administrator@example.com",
        "version": "4 F3"
    },
    "key": "about_info",
    "meta": {
        "href": "/api/info",
        "parent": "/api"
    }
}
Element Description      
build_date Build date of the SCB firmware. This element is included in the response only for authenticated users.      
domainname Name of the domain used on the network. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 3.2.5, Naming options.      
hostname Name of the machine running SCB. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 3.2.5, Naming options.      
nickname The nickname of the SCB host. Use it to distinguish the devices. It is displayed in the core and boot login shells. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 3.2.5, Naming options.      
support_link The e-mail address of the SCB administrator, as set in the admin_address parameter of the /api/configuration/management/email endpoint. For details, see Section 3.4.4, Mail settings.      
firmware_version The version number of the firmware running on SCB, for example, 4.3.2a. This element is included in the response only for authenticated users.      
firmware_version The version number of the firmware running on SCB, for example, 4.3.2a. This element is included in the response only for authenticated users.      
version The name of the major release running on SCB, for example, 4 F3. This element is included in the response only for authenticated users.      

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.

3.2. Network settings

3.2.1. Web interface

Configuration options for the web interface of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/webinterface

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options for the SCB web interface.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/webinterface

Response

The following is a sample response received when listing the configuration options of the SCB web interface. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "timeout": 10
  },
  "key": "webinterface",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/webinterface",
    "last": "/api/configuration/management/webinterface",
    "next": null,
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/syslog",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the configuration options of the SCB web interface.
  timeout int Session timeout, in minutes.

Modify the configuration of the web interface

To modify the configuration of the web interface, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/webinterface endpoint. You can find a detailed description of the available parameters listed in Web interface.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.2. Network configuration options

Contains the endpoints for configuring networking on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/network

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists network configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network

Response

The following is a sample response received when listing network configuration options. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "dns",
      "meta": {
        "href": "/api/configuration/network/dns"
      }
    },
    {
      "key": "ip_forwarding_rule_pairs",
      "meta": {
        "href": "/api/configuration/network/ip_forwarding_rule_pairs"
      }
    },
    {
      "key": "naming",
      "meta": {
        "href": "/api/configuration/network/naming"
      }
    },
    {
      "key": "nics",
      "meta": {
        "href": "/api/configuration/network/nics"
      }
    },
    {
      "key": "routing",
      "meta": {
        "href": "/api/configuration/network/routing"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/network",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/passwords",
    "parent": "/api/configuration",
    "previous": "/api/configuration/management",
    "transaction": "/api/transaction"
  }
}
Element Description
dns The address of the primary and secondary DNS server.
ip_forwarding_rule_pairs Rules for routing between the network interfaces.
naming DNS search domain, hostname, and appliance nickname settings.
nics References the endpoints of the three physical network interfaces.
routing Routing table. Defines the address of the gateway server for each configured subnet.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.3. DNS servers

Contains the address of the primary and secondary DNS server.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/dns

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configured DNS servers.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/dns

Response

The following is a sample response received when listing the configured DNS servers. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "primary": "192.168.56.1",
    "secondary": null
  },
  "key": "dns",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/dns",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/ip_forwarding_rule_pairs",
    "parent": "/api/configuration/network",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoints.
body   Top level element (string) Contains the addresses of the DNS servers.
  primary string The IP address of the primary DNS server.
  secondary string The address of the secondary DNS server.

Modify the address of the DNS servers

To modify the addres of a DNS server, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/dns endpoint. You can find a detailed description of the available parameters listed in DNS servers.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.4. Routing between interfaces

Configures routing between network interfaces. To use an interface in single-interface router mode, configure both interface_a and interface_b elements to reference that same interface.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists interface routing rules.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs

Response

The following is a sample response received when listing interface routing rules. For details of the meta object, see Section 1.1, Message format.

{
  "body": [
    {
      "interface_a": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      },
      "interface_b": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      }
    }
  ],
  "key": "ip_forwarding_rule_pairs",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/ip_forwarding_rule_pairs",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/naming",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/dns",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (list) Contains the rules for routing between the network interfaces.
  interface_a string

References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint.

To modify or add a network interface, use the value of the returned key as the value of the interface_a element, and remove any child elements (including the key).

  interface_b string

References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint.

To modify or add a network interface, use the value of the returned key as the value of the interface_b element, and remove any child elements (including the key).

Add a rule for routing between the network interfaces

To add a rule, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new list of rules. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs endpoint. You can find a detailed description of the available parameters listed in Routing between interfaces.

    If the POST request is successful, the response includes the key of the new rule.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a rule for routing between the network interfaces

To modify a rule, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the list of rules. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs endpoint. You can find a detailed description of the available parameters listed in Routing between interfaces.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.5. Naming options

Contains the settings for the DNS search domain, hostname, and appliance nickname.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/naming

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the naming settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/naming

Response

The following is a sample response received when listing naming settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "domainname": "balabit",
    "hostname": "scb-api-docs",
    "nickname": null
  },
  "key": "naming",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/naming",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/nics",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/ip_forwarding_rule_pairs",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the naming settings.
  domainname string The domain name of the network.
  hostname string The hostname of SCB.
  nickname string The nickname for the appliance. Use this name to distinguish between multiple SCB appliances on the network. This name is visible in the boot and core login shells.

Modify a name

To modify a name, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/naming endpoint. You can find a detailed description of the available parameters listed in Naming settings.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.6. Network addresses

Contains the network addresses configured for each physical NIC.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/nics

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints for the physical network interfaces.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/

The following commands retrieve the properties of a specific physical network interface.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic1
curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic2
curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic3

Response

The following is a sample response received when listing physical network interfaces. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "nic1",
      "meta": {
        "href": "/api/configuration/network/nics/nic1"
      }
    },
    {
      "key": "nic2",
      "meta": {
        "href": "/api/configuration/network/nics/nic2"
      }
    },
    {
      "key": "nic3",
      "meta": {
        "href": "/api/configuration/network/nics/nic3"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/nics",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/routing",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/naming",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific physical network interface, the response is the following.

{
  "body": {
    "interfaces": {
      "@order": [
        "ff7574025754b3df1647001"
      ],
      "ff7574025754b3df1647001": {
        "addresses": {
          "1": "192.168.56.101/24",
          "4323998795727ae1ab8750": "192.168.56.151/24",
          "@order": [
            "1",
            "4323998795727ae1ab8750"
          ]
        },
        "name": "default",
        "vlantag": 0
      }
    },
    "name": "eth0",
    "speed": "auto"
  },
  "key": "nic1",
  "meta": {
    "first": "/api/configuration/network/nics/nic1",
    "href": "/api/configuration/network/nics/nic1",
    "last": "/api/configuration/network/nics/nic3",
    "next": "/api/configuration/network/nics/nic2",
    "parent": "/api/configuration/network/nics",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the physical network interface (nic1, nic2 or nic3).
body   Top level element (string) Contains the properties of the physical network interface.
  interfaces Top level item Contains the configuration of all virtual interfaces on the physical NIC.
  name string The system name of the physical network interface (eth0, eth1 or eth2). Do not change this value.
  speed string

The speed of the physical network interface. The default value is auto. Change this setting only for troubleshooting purposes. Possible values are:

  • auto

    Negotiate the network speed automatically. This is the default value.

  • 10-half

    10BaseT/Half.

  • 100-half

    100BaseT/Half.

  • 10-full

    10BaseT/Full.

  • 100-full

    100BaseT/Full.

  • 1000-full

    1000BaseT/Full.

Elements of interfaces Type Description
@order     list

Lists the keys of the interfaces in the order they are be displayed on the SCB web UI.

<key-of-an-interface>     string

Contains the addresses, name, and vlantag of the network interface.

Each physical NIC has an automatically created interface key, where the value of the vlanid element is set to 0.

To add a valid virtual network interface to the physical NIC, create an additional interface, and assign a value between 1 and 4094 to its vlanid element.

  addresses   string Contains the addresses of the interface, and their display order.
    <key-of-address> string Contains the IP address range.
    @order list Lists the keys of the addresses in the order they are be displayed on the SCB web UI.
  name   string The name of the interface, as displayed on the SCB web UI.
  vlantag   string

The ID of the interface.

For the physical interface, the value is 0. For virtual interfaces, the value is between 1 and 4094.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.7. Routing table

Contains the address of the gateway server for each configured subnet.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/routing

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configured subnets and the corresponding gateway servers.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/routing

Response

The following is a sample response received when viewing the routing table. For details of the meta object, see Section 1.1, Message format.

{
  "body": [
    {
      "gateway": "192.168.56.1",
      "target_network": "0.0.0.0/0"
    }
  ],
  "key": "routing",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/routing",
    "last": "/api/configuration/network/routing",
    "next": null,
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/nics",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (list) Contains the routing table.
  gateway string The IP address of the gateway server.
  target_network string The network id (IP address and subnet mask) of the subnet.

Add a subnet

To add a subnet, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new routing table. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/network/routing endpoint. You can find a detailed description of the available parameters listed in Routing table.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify the routing table

To modify the routing table, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the routing table. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/netowrk/routing endpoint. You can find a detailed description of the available parameters listed in Routing table.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.8. Local services of SCB

Contains the endpoints for configuring the local services of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the local services.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services

Response

The following is a sample response received when listing local services. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "admin_web",
            "meta": {
                "href": "/api/configuration/local_services/admin_web"
            }
        },
        {
            "key": "indexer",
            "meta": {
                "href": "/api/configuration/local_services/indexer"
            }
        },
        {
            "key": "postgresql",
            "meta": {
                "href": "/api/configuration/local_services/postgresql"
            }
        },
        {
            "key": "snmp_agent",
            "meta": {
                "href": "/api/configuration/local_services/snmp_agent"
            }
        },
        {
            "key": "ssh",
            "meta": {
                "href": "/api/configuration/local_services/ssh"
            }
        },
        {
            "key": "user_web",
            "meta": {
                "href": "/api/configuration/local_services/user_web"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa",
        "href": "/api/configuration/local_services",
        "last": "/api/configuration/x509",
        "next": "/api/configuration/management",
        "parent": "/api/configuration",
        "previous": "/api/configuration/ica",
        "transaction": "/api/transaction"
    }
}
Element Description
admin_web Web login for administrators and users: On this address, users can, depending on their access privileges, modify the configuration of SCB, and perform authentication-related activities (gateway authentication, 4-eyes authorization).
indexer Configure the indexer services of SCB, including remote indexing.
postgresql Configure direct remote access to the connection database of SCB.
snmp_agent Configure the SNMP server of SCB.
ssh Configure remote SSH access to SCB.
user_web

Web login for users only: The configuration of SCB cannot be viewed or altered from this address. Users (even ones with administrator privileges) can only perform gateway authentication and 4-eyes authorization.

Warning

Note that the web login for users only (Basic Settings > Local Services > Web (user only)) feature of SCB is deprecated and will be removed from SCB version 5 LTS. In 5 LTS, you will be able to set the same functionality using authorization settings.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.9. Local services — Web login for administrators

The SCB administrators and users can, depending on their access privileges, modify the configuration of SCB, and perform authentication-related activities (gateway authentication, 4-eyes authorization). On this endpoint you can configure on which interfaces can the administrators access SCB, and optionally restrict the access to these interfaces.

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services/admin_web

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services/admin_web

Response

The following is a sample response received when listing the configuration options. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "access_restriction": {
            "allowed_from": [
                "10.40.0.0/16"
            ],
            "enabled": true
        },
        "bruteforce_protection": true,
        "listen": [
            {
                "address": {
                    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
                    "meta": {
                        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
                    }
                },
                "http_port": 80,
                "https_port": 443
            }
        ]
    },
    "key": "admin_web",
    "meta": {
        "first": "/api/configuration/local_services/admin_web",
        "href": "/api/configuration/local_services/admin_web",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/indexer",
        "parent": "/api/configuration/local_services",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options of the SCB web interface.
  access_restriction   JSON object Enables and configures limitations on the clients that can access the web interface, based on the IP address of the clients.
    allowed_from list The list of IP networks from where the administrators are permitted to access this management interface. To specify the IP addresses or networks, use the IPv4-Address/prefix format, for example, 10.40.0.0/16.
    enabled boolean Set it to true to restrict access to the specified client addresses.
  bruteforce_protection   boolean Enables protection against brute-force attacks by denying access after failed login attempts for increasingly longer period. Enabled by default.
  listen   list Selects the network interface, IP address, and port where the clients can access the web interface.
    address JSON object

A reference to a configured network interface and IP address where this local service accepts connections. For example, if querying the interface /api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/ returns the following response:

{
    "body": {
        "interfaces": {
            "@order": [
                "ff7574025754b3df1647001"
            ],
            "ff7574025754b3df1647001": {
                "addresses": {
                    "1": "10.40.255.171/24",
                    "@order": [
                        "1"
                    ]
                },
                "name": "default",
                "vlantag": 0
            }
        },
        "name": "eth0",
        "speed": "auto"
    },
    "key": "nic1",
    "meta": {
        "first": "/api/configuration/network/nics/nic1",
        "href": "/api/configuration/network/nics/nic1",
        "last": "/api/configuration/network/nics/nic3",
        "next": "/api/configuration/network/nics/nic2",
        "parent": "/api/configuration/network/nics",
        "previous": null,
        "transaction": "/api/transaction"
    }
    }

Then the listening address of the local service is the following.

nic1.interfaces.ff7574025754b3df1647001.addresses.1

This is the format you have to use when configuring the address of the local service using REST:

"address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1"

When querying a local services endpoint, the response will contain a reference to the IP address of the interface in the following format:

"address": {
    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
    "meta": {
        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
    }
    },
    http_port integer The port number where SCB accepts HTTP connections. Note that SCB automatically redirects connections from this port to the HTTPS port set in https_port.
    https_port integer The port number where SCB accepts HTTPS connections.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.2.10. Local services — Web login for users

The SCB users can perform authentication-related activities (gateway authentication, 4-eyes authorization). On this endpoint you can configure on which interfaces can the users access SCB, and optionally restrict the access to these interfaces.

Warning

Note that the web login for users only (Basic Settings > Local Services > Web (user only)) feature of SCB is deprecated and will be removed from SCB version 5 LTS. In 5 LTS, you will be able to set the same functionality using authorization settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services/user_web

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services/user_web

Response

The following is a sample response received when listing the configuration options. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "access_restriction": {
            "allowed_from": [
                "10.40.0.0/16"
            ],
            "enabled": true
        },
        "bruteforce_protection": true,
        "listen": [
            {
                "address": {
                    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
                    "meta": {
                        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
                    }
                },
                "http_port": 80,
                "https_port": 443
            }
        ]
    },
    "key": "user_web",
    "meta": {
        "first": "/api/configuration/local_services/user_web",
        "href": "/api/configuration/local_services/user_web",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/indexer",
        "parent": "/api/configuration/local_services",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options of the SCB web interface.
  access_restriction   JSON object Enables and configures limitations on the clients that can access the web interface, based on the IP address of the clients.
    allowed_from list The list of IP networks from where the administrators are permitted to access this management interface. To specify the IP addresses or networks, use the IPv4-Address/prefix format, for example, 10.40.0.0/16.
    enabled boolean Set it to true to restrict access to the specified client addresses.
  bruteforce_protection   boolean Enables protection against brute-force attacks by denying access after failed login attempts for increasingly longer period. Enabled by default.
  listen   list Selects the network interface, IP address, and port where the clients can access the web interface.
    address JSON object

A reference to a configured network interface and IP address where this local service accepts connections. For example, if querying the interface /api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/ returns the following response:

{
    "body": {
        "interfaces": {
            "@order": [
                "ff7574025754b3df1647001"
            ],
            "ff7574025754b3df1647001": {
                "addresses": {
                    "1": "10.40.255.171/24",
                    "@order": [
                        "1"
                    ]
                },
                "name": "default",
                "vlantag": 0
            }
        },
        "name": "eth0",
        "speed": "auto"
    },
    "key": "nic1",
    "meta": {
        "first": "/api/configuration/network/nics/nic1",
        "href": "/api/configuration/network/nics/nic1",
        "last": "/api/configuration/network/nics/nic3",
        "next": "/api/configuration/network/nics/nic2",
        "parent": "/api/configuration/network/nics",
        "previous": null,
        "transaction": "/api/transaction"
    }
    }

Then the listening address of the local service is the following.

nic1.interfaces.ff7574025754b3df1647001.addresses.1

This is the format you have to use when configuring the address of the local service using REST:

"address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1"

When querying a local services endpoint, the response will contain a reference to the IP address of the interface in the following format:

"address": {
    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
    "meta": {
        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
    }
    },
    http_port integer The port number where SCB accepts HTTP connections. Note that SCB automatically redirects connections from this port to the HTTPS port set in https_port.
    https_port integer The port number where SCB accepts HTTPS connections.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.3. Date and time

3.3.1. Date & time

Contains the endpoints for configuring date and time on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/datetime

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists endpoints for configuring date and time settings on SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/datetime

Response

The following is a sample response received when listing the endpoints for date and time settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "ntp_servers",
      "meta": {
        "href": "/api/configuration/datetime/ntp_servers"
      }
    },
    {
      "key": "timezone",
      "meta": {
        "href": "/api/configuration/datetime/timezone"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/datetime",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/http",
    "parent": "/api/configuration",
    "previous": "/api/configuration/alerting",
    "transaction": "/api/transaction"
  }
}
Element Description      
ntp_servers NTP server addresses.      
timezone Timezone settings.      

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.3.2. NTP servers

This endpoint contains NTP server addresses.

URL

GET https://<IP-address-of-SCB>/api/configuration/datetime/ntp_servers

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists NTP server addresses.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/datetime/ntp_servers

Response

The following is a sample response received when listing NTP server addresses. For details of the meta object, see Section 1.1, Message format.

{
  "body": [
    {
      "selection": "fqdn",
      "value": "pool.ntp.org"
    }
  ],
  "key": "ntp_servers",
  "meta": {
    "first": "/api/configuration/datetime/ntp_servers",
    "href": "/api/configuration/datetime/ntp_servers",
    "last": "/api/configuration/datetime/timezone",
    "next": "/api/configuration/datetime/timezone",
    "parent": "/api/configuration/datetime",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (list) Contains the list of NTP server addresses.
  selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The NTP server address is provided as a fully qualified domain name.

  • ip

    The NTP server address is provided as an IP address.

  value string The address of the NTP server.

Add an NTP server

To add an NTP server's address, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new NTP server address list. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/datetime/ntp_servers endpoint. You can find a detailed description of the available parameters listed in NTP servers.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify an NTP server address

To modify an NTP server's address, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the NTP server address list. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/datetime/ntp_servers endpoint. You can find a detailed description of the available parameters listed in NTP servers.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.3.3. Timezone

Configures the time zone.

URL

GET https://<IP-address-of-SCB>/api/configuration/datetime/timezone

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command displays the configured time zone.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/datetime/timezone

Response

The following is a sample response received when querying the configured time zone. For details of the meta object, see Section 1.1, Message format.

{
  "body": "America/New_York",
  "key": "timezone",
  "meta": {
    "first": "/api/configuration/datetime/ntp_servers",
    "href": "/api/configuration/datetime/timezone",
    "last": "/api/configuration/datetime/timezone",
    "next": null,
    "parent": "/api/configuration/datetime",
    "previous": "/api/configuration/datetime/ntp_servers",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body string

Contains the configured time zone. Possible values are:

Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara
Africa/Asmera
Africa/Bamako
Africa/Bangui
Africa/Banjul
Africa/Bissau
Africa/Blantyre
Africa/Brazzaville
Africa/Bujumbura
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/Conakry
Africa/Dakar
Africa/Dar_es_Salaam
Africa/Djibouti
Africa/Douala
Africa/El_Aaiun
Africa/Freetown
Africa/Gaborone
Africa/Harare
Africa/Johannesburg
Africa/Kampala
Africa/Khartoum
Africa/Kigali
Africa/Kinshasa
Africa/Lagos
Africa/Libreville
Africa/Lome
Africa/Luanda
Africa/Lubumbashi
Africa/Lusaka
Africa/Malabo
Africa/Maputo
Africa/Maseru
Africa/Mbabane
Africa/Mogadishu
Africa/Monrovia
Africa/Nairobi
Africa/Ndjamena
Africa/Niamey
Africa/Nouakchott
Africa/Ouagadougou
Africa/Porto-Novo
Africa/Sao_Tome
Africa/Timbuktu
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
America/Adak
America/Anchorage
America/Anguilla
America/Antigua
America/Araguaina
America/Argentina/Buenos_Aires
America/Argentina/Catamarca
America/Argentina/ComodRivadavia
America/Argentina/Cordoba
America/Argentina/Jujuy
America/Argentina/La_Rioja
America/Argentina/Mendoza
America/Argentina/Rio_Gallegos
America/Argentina/San_Juan
America/Argentina/Tucuman
America/Argentina/Ushuaia
America/Aruba
America/Asuncion
America/Atikokan
America/Atka
America/Bahia
America/Barbados
America/Belem
America/Belize
America/Blanc-Sablon
America/Boa_Vista
America/Bogota
America/Boise
America/Buenos_Aires
America/Cambridge_Bay
America/Campo_Grande
America/Cancun
America/Caracas
America/Catamarca
America/Cayenne
America/Cayman
America/Chicago
America/Chihuahua
America/Coral_Harbour
America/Cordoba
America/Costa_Rica
America/Cuiaba
America/Curacao
America/Danmarkshavn
America/Dawson
America/Dawson_Creek
America/Denver
America/Detroit
America/Dominica
America/Edmonton
America/Eirunepe
America/El_Salvador
America/Ensenada
America/Fort_Wayne
America/Fortaleza
America/Glace_Bay
America/Godthab
America/Goose_Bay
America/Grand_Turk
America/Grenada
America/Guadeloupe
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Hermosillo
America/Indiana/Indianapolis
America/Indiana/Knox
America/Indiana/Marengo
America/Indiana/Petersburg
America/Indiana/Tell_City
America/Indiana/Vevay
America/Indiana/Vincennes
America/Indiana/Winamac
America/Indianapolis
America/Inuvik
America/Iqaluit
America/Jamaica
America/Jujuy
America/Juneau
America/Kentucky/Louisville
America/Kentucky/Monticello
America/Knox_IN
America/La_Paz
America/Lima
America/Los_Angeles
America/Louisville
America/Maceio
America/Managua
America/Manaus
America/Marigot
America/Martinique
America/Mazatlan
America/Mendoza
America/Menominee
America/Merida
America/Mexico_City
America/Miquelon
America/Moncton
America/Monterrey
America/Montevideo
America/Montreal
America/Montserrat
America/Nassau
America/New_York
America/Nipigon
America/Nome
America/Noronha
America/North_Dakota/Center
America/North_Dakota/New_Salem
America/Panama
America/Pangnirtung
America/Paramaribo
America/Phoenix
America/Port-au-Prince
America/Port_of_Spain
America/Porto_Acre
America/Porto_Velho
America/Puerto_Rico
America/Rainy_River
America/Rankin_Inlet
America/Recife
America/Regina
America/Resolute
America/Rio_Branco
America/Rosario
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/Shiprock
America/St_Barthelemy
America/St_Johns
America/St_Kitts
America/St_Lucia
America/St_Thomas
America/St_Vincent
America/Swift_Current
America/Tegucigalpa
America/Thule
America/Thunder_Bay
America/Tijuana
America/Toronto
America/Tortola
America/Vancouver
America/Virgin
America/Whitehorse
America/Winnipeg
America/Yakutat
America/Yellowknife
US/Alaska
US/Aleutian
US/Arizona
US/Central
US/East-Indiana
US/Eastern
US/Hawaii
US/Indiana-Starke
US/Michigan
US/Mountain
US/Pacific
US/Samoa
Canada/Atlantic
Canada/Central
Canada/East-Saskatchewan
Canada/Eastern
Canada/Mountain
Canada/Newfoundland
Canada/Pacific
Canada/Saskatchewan
Canada/Yukon
Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Ashkhabad
Asia/Baghdad
Asia/Bahrain
Asia/Baku
Asia/Bangkok
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Calcutta
Asia/Choibalsan
Asia/Chongqing
Asia/Chungking
Asia/Colombo
Asia/Dacca
Asia/Damascus
Asia/Dhaka
Asia/Dili
Asia/Dubai
Asia/Dushanbe
Asia/Gaza
Asia/Harbin
Asia/Hong_Kong
Asia/Hovd
Asia/Irkutsk
Asia/Istanbul
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Kashgar
Asia/Katmandu
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuching
Asia/Kuwait
Asia/Macao
Asia/Macau
Asia/Magadan
Asia/Makassar
Asia/Manila
Asia/Muscat
Asia/Nicosia
Asia/Novosibirsk
Asia/Omsk
Asia/Oral
Asia/Phnom_Penh
Asia/Pontianak
Asia/Pyongyang
Asia/Qatar
Asia/Qyzylorda
Asia/Rangoon
Asia/Riyadh
Asia/Riyadh87
Asia/Riyadh88
Asia/Riyadh89
Asia/Saigon
Asia/Sakhalin
Asia/Samarkand
Asia/Seoul
Asia/Shanghai
Asia/Singapore
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Tel_Aviv
Asia/Thimbu
Asia/Thimphu
Asia/Tokyo
Asia/Ujung_Pandang
Asia/Ulaanbaatar
Asia/Ulan_Bator
Asia/Urumqi
Asia/Vientiane
Asia/Vladivostok
Asia/Yakutsk
Asia/Yekaterinburg
Asia/Yerevan
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faeroe
Atlantic/Faroe
Atlantic/Jan_Mayen
Atlantic/Madeira
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/St_Helena
Atlantic/Stanley
Australia/ACT
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Canberra
Australia/Currie
Australia/Darwin
Australia/Eucla
Australia/Hobart
Australia/LHI
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/NSW
Australia/North
Australia/Perth
Australia/Queensland
Australia/South
Australia/Sydney
Australia/Tasmania
Australia/Victoria
Australia/West
Australia/Yancowinna
Europe/Amsterdam
Europe/Andorra
Europe/Athens
Europe/Belfast
Europe/Belgrade
Europe/Berlin
Europe/Bratislava
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Guernsey
Europe/Helsinki
Europe/Isle_of_Man
Europe/Istanbul
Europe/Jersey
Europe/Kaliningrad
Europe/Kiev
Europe/Lisbon
Europe/Ljubljana
Europe/London
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Mariehamn
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Nicosia
Europe/Oslo
Europe/Paris
Europe/Podgorica
Europe/Prague
Europe/Riga
Europe/Rome
Europe/Samara
Europe/San_Marino
Europe/Sarajevo
Europe/Simferopol
Europe/Skopje
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Tiraspol
Europe/Uzhgorod
Europe/Vaduz
Europe/Vatican
Europe/Vienna
Europe/Vilnius
Europe/Volgograd
Europe/Warsaw
Europe/Zagreb
Europe/Zaporozhye
Europe/Zurich
Indian/Antananarivo
Indian/Chagos
Indian/Christmas
Indian/Cocos
Indian/Comoro
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Mayotte
Indian/Reunion
Pacific/Apia
Pacific/Auckland
Pacific/Chatham
Pacific/Easter
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Funafuti
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Johnston
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Kwajalein
Pacific/Majuro
Pacific/Marquesas
Pacific/Midway
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pago_Pago
Pacific/Palau
Pacific/Pitcairn
Pacific/Ponape
Pacific/Port_Moresby
Pacific/Rarotonga
Pacific/Saipan
Pacific/Samoa
Pacific/Tahiti
Pacific/Tarawa
Pacific/Tongatapu
Pacific/Truk
Pacific/Wake
Pacific/Wallis
Pacific/Yap
Etc/GMT
Etc/GMT+0
Etc/GMT+1
Etc/GMT+10
Etc/GMT+11
Etc/GMT+12
Etc/GMT+2
Etc/GMT+3
Etc/GMT+4
Etc/GMT+5
Etc/GMT+6
Etc/GMT+7
Etc/GMT+8
Etc/GMT+9
Etc/GMT-0
Etc/GMT-1
Etc/GMT-10
Etc/GMT-11
Etc/GMT-12
Etc/GMT-13
Etc/GMT-14
Etc/GMT-2
Etc/GMT-3
Etc/GMT-4
Etc/GMT-5
Etc/GMT-6
Etc/GMT-7
Etc/GMT-8
Etc/GMT-9
Etc/GMT0
Etc/Greenwich
Etc/UCT
Etc/UTC
Etc/Universal
Etc/Zulu

Modify the time zone

To modify time zone, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the body element. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/datetime/timezone endpoint. You can find a detailed description of the available time zone values listed in Time zone.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4. Logs, monitoring and alerts

3.4.1. Management options

Contains the configuration endpoints for managing SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists management configuration endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management

Response

The following is a sample response received when listing management endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "certificates",
      "meta": {
        "href": "/api/configuration/management/certificates"
      }
    },
    {
      "key": "disk_fillup_prevention",
      "meta": {
        "href": "/api/configuration/management/disk_fillup_prevention"
      }
    },
    {
      "key": "email",
      "meta": {
        "href": "/api/configuration/management/email"
      }
    },
    {
      "key": "health_monitoring",
      "meta": {
        "href": "/api/configuration/management/health_monitoring"
      }
    },
    {
      "key": "snmp",
      "meta": {
        "href": "/api/configuration/management/snmp"
      }
    },
    {
      "key": "soap",
      "meta": {
        "href": "/api/configuration/management/soap"
      }
    },
    {
      "key": "syslog",
      "meta": {
        "href": "/api/configuration/management/syslog"
      }
    },
    {
      "key": "webinterface",
      "meta": {
        "href": "/api/configuration/management/webinterface"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/management",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/network",
    "parent": "/api/configuration",
    "previous": "/api/configuration/local_services",
    "transaction": "/api/transaction"
  }
}
Endpoints Description
certificates References the certificates of SCB's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web interface.
disk_fillup_prevention Disk fill-up prevention.
email SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.
health_monitoring Configuration settings for monitoring the utilization of SCB.
snmp SNMP settings.
soap Configuration settings for the RPC API.
syslog Syslog server address and authentication.
webinterface Configuration settings for the SCB web interface.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.2. Syslog server settings

SCB can send its system log messages to remote syslog servers, for example, syslog-ng Premium Edition, syslog-ng Store Box, Splunk, or HPE ArcSight Data Platform.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/syslog

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the syslog server settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/syslog

Response

The following is a sample response received when listing syslog server settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "certificates": {
      "ca": "<ca-cert>",
      "client": {
        "key": "191725ec-b71b-47ab-9e87-561a5d9e2bb7",
        "meta": {
          "href": "/api/configuration/x509/191725ec-b71b-47ab-9e87-561a5d9e2bb7"
        }
      }
    },
    "include_node_id": true,
    "receivers": [
      {
        "address": {
          "selection": "ip",
          "value": "10.20.30.40"
        },
        "port": 514,
        "protocol": {
          "ip_protocol": "tcp",
          "protocol_type": "legacy-bsd",
          "tls_enabled": false
        }
      }
    ],
    "server_key_check": "optional-trusted"
  },
  "key": "syslog",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/syslog",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/webinterface",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/soap",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the syslog server configuration settings.
  certificates   Top level item Contains the certificates of the client (SCB), and the certificate of the CA.
    ca string

The CA certificate of the Certificate Authority. Configure this option if the value of the tls_enabled element is set to true.

    client string

Configure this option if the value of the tls_enabled element is set to true, and the syslog server requires mutual authentication. Otherwise, set its value to null.

References the identifier of the client's (SCB's) X.509 certificate. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  include_node_id   boolean

Set to true to display separate hostnames for syslog messages sent by the nodes of a SCB HA cluster.

The node ID included in the hostname filed of the syslog message is the MAC address of the node's HA interface. Messages of the core firmware are always sent by the master node.

  receivers   Top level list Contains the addresses of the syslog servers.
  server_key_check   string

Configures validating the syslog server's certificate with the CA. The following values are possible:

  • optional-trusted

    If the server sends a certificate, SCB checks if it is valid (not expired) and that the Common Name of the certificate contains the domain name or the IP address of the server. If these checks fail, SCB rejects the connection. However, SCB accepts the connection if the server does not send a certificate.

  • optional-untrusted

    SCB accepts any certificate shown by the server.

  • required-trusted

    SCB verifies the certificate shown by the server.

  • required-untrusted

    SCB requests a certificate from the server, and rejects the connection if no certificate is received, if the certificate is not valid (expired), or if the Common Name of the certificate does not contain the domain name or the IP address of the server.

Elements of receivers Type Description
address   Top level item Contains the address of the syslog server.
  selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The syslog server address is provided as a fully qualified domain name.

  • ip

    The syslog server address is provided as an IP address.

  value string The address of the syslog server.
port   int The port of the syslog server.
protocol   Top level item Contains the syslog protocol settings.
  ip_protocol string

Configures the IP protocol. The following options are available:

  • tcp

    TCP protocol.

  • udp

    UDP protocol.

  protocol_type string

Configures the syslog protocol. The following options are available:

  • legacy-bsd

    BSD-syslog protocol.

  • syslog

    IETF-syslog protocol.

  tls_enabled string

Set to true to enable TLS encryption.

If TLS is enabled, the value of the ca and client elements cannot be null.

Examples: 

Default settings: no external syslog servers.

{
  "certificates": {
    "ca": null,
    "client": null
  },
  "include_node_id": true,
  "receivers": [],
  "server_key_check": "optional-untrusted"
}

Uploading CA certificates

SCB uses only the key part of the CA certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Modify syslog server settings

To modify the syslog server settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/syslog endpoint. You can find a detailed description of the available parameters listed in Syslog server.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.3. Disk fill-up prevention

Contains the configuration options for preventing disk fill-up.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists disk fill-up prevention options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention

Response

The following is a sample response received when listing disk fill-up prevention settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "archiving_enabled": false,
    "enabled": true,
    "used_space_ratio_limit": 80
  },
  "key": "disk_fillup_prevention",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/disk_fillup_prevention",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/email",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/certificates",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the configuration settings for disk fill-up prevention.
  archiving_enabled boolean

Set to true to automatically start all configured archiving/cleanup jobs when disk usage goes over the value of the used_space_ratio_limit element.

  enabled boolean Set to true to enable disk fill-up prevention.
  used_space_ratio_limit int

Disk utilization limit, in percent. When used disk space reaches this limit, SCB disconnects all clients.

Set to 0 to turn the feature off.

Modify disk fill-up prevention settings

To modify the disk fill-up prevention settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the disk fill-up configuration endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention endpoint. You can find a detailed description of the available parameters listed in Disk fill-up prevention.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.4. Mail settings

Configuration settings for SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/email

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists mail settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/email

Response

The following is a sample response received when listing mail settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "admin_address": "<admin-email>",
    "alerting_address": "<alerts-target-email>",
    "reporting_address": "<reports-target-email>",
    "sender_address": null,
    "smtp_auth": {
      "enabled": false
    },
    "smtp_encryption": {
      "selection": "disabled"
    },
    "smtp_server": {
      "selection": "ip",
      "value": "<smtp-server-ip>"
    }
  },
  "key": "email",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/email",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/health_monitoring",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/disk_fillup_prevention",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options for e-mail.
  admin_address   string The e-mail address of the administrator of SCB.
  alerting_address   string The e-mail address where monitoring alerts are sent.
  reporting_address   string The e-mail address where traffic reports are sent.
  sender_address   string The address of the sender (SCB).
  smtp_auth   Top level item Configures authentication to the SMTP server.
    enabled boolean Set to true to enable authenticating to the SMTP server.
    password string

References the password of the authenticating user. You configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

    username string The username for authenticating to the SMTP server.
  smtp_encryption   Top level item Configuration settings for encrypting the communication between SCB and the SMTP server.
  smtp_server   Top level item Contains the address of the SMTP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The SMTP server address is provided as a fully qualified domain name.

  • ip

    The SMTP server address is provided as an IP address.

    value string The address of the SMTP server.
Elements of smtp_encryption Type Description
client_authentication   Top level item

Configures authenticating as a client with an X.509 certificate.

Can only be enabled if the value of the selection element is set to starttls.

  enabled boolean

Set to true to enable authenticating as a client with an X.509 certificate.

Can only be enabled if the value of the selection element of snmp_encryption is set to starttls.

  x509_identity  

References the identifier of the authenticating client's X.509 certificate. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). For details, see Section 5.5, Certificates stored on SCB.

selection   string

Configures encrypted communication with the SMTP server. The following values are possible:

  • disabled

    Disables e-mail encryption.

  • starttls

    Enables STARTTLS encryption.

server_certificate_check   Top level item

Configuration settings for validating the SMTP server's certificate.

Can only be enabled if the value of the selection element is set to starttls.

  enabled boolean

Set to true to enable validating the SMTP server's certificate.

Can only be enabled if the value of the selection element of snmp_encryption is set to starttls.

  server_certificate_ca string The CA certificate of the Certificate Authority.

Examples: 

Enable authentication to the SMTP server.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "aec663b5-f5bd-4c93-bb51-36fea3328e58",
      "meta": {
        "href": "/api/configuration/passwords/aec663b5-f5bd-4c93-bb51-36fea3328e58"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "selection": "disabled"
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

Configure STARTTLS encryption without certificate checks.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "0210848a-b301-47d5-9023-779c5fe951f7",
      "meta": {
        "href": "/api/configuration/passwords/0210848a-b301-47d5-9023-779c5fe951f7"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "client_authentication": {
      "enabled": false
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": false
    }
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

Configure STARTTLS encryption with server certificate check, and authenticate as client with an X.509 certificate.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "37716c4f-759d-4900-9740-ea22211498cf",
      "meta": {
        "href": "/api/configuration/passwords/37716c4f-759d-4900-9740-ea22211498cf"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "client_authentication": {
      "enabled": true,
      "x509_identity": {
        "key": "c3a23e32-d75b-461e-afc0-14d1f6692879",
        "meta": {
          "href": "/api/configuration/x509/c3a23e32-d75b-461e-afc0-14d1f6692879"
        }
      }
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": true,
      "server_certificate_ca": "<ca-cert>"
    }
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

CA certificates

CA certificates must not contain any metadata. SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Modify mail settings

To modify mail settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/email endpoint. You can find a detailed description of the available parameters listed in Mail settings.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.5. Health monitoring

Configuration settings for monitoring the utilization of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/health_monitoring

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists health monitoring settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/health_monitoring

Response

The following is a sample response received when listing health monitoring settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "maximum_disk_utilization_ratio": 80,
    "maximum_load1": null,
    "maximum_load15": null,
    "maximum_load5": null,
    "maximum_swap_utilization_ratio": 70
  },
  "key": "health_monitoring",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/health_monitoring",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/snmp",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/email",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains health monitoring settings.
  maximum_disk_utilization_ratio int The highest allowed value for disk utilization (in %).
  maximum_load1 int Average maximum for load for 1 minute.
  maximum_load15 int Average maximum load for 15 minutes.
  maximum_load5 int Average maximum load for 5 minutes.
  maximum_swap_utilization_ratio int The highest allowed value for swap utilization (in %).

Modify health monitoring settings

To modify health monitoring settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/health_monitoring endpoint.You can find a detailed description of the available parameters listed in Health monitoring.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.6. SNMP settings

Contains the configuration endpoints for SNMP settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/snmp

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints for SNMP configuration settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/snmp

Response

The following is a sample response received when listing SNMP configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "trap",
      "meta": {
        "href": "/api/configuration/management/snmp/trap"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/snmp",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/soap",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/health_monitoring",
    "transaction": "/api/transaction"
  }
}
Element Description
trap Configuration settings for SNMP traps.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.7. SNMP traps

Configuration settings for the address and protocol of the SNMP server.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/snmp/trap

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration of the SNMP server.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/snmp/trap

Response

The following is a sample response received when listing the address and protocol settings of the SNMP server. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "enabled": true,
    "version": {
      "selection": "2c",
      "value": {
        "community": "public",
        "server": {
          "selection": "ip",
          "value": "10.20.30.40"
        }
      }
    }
  },
  "key": "trap",
  "meta": {
    "first": "/api/configuration/management/snmp/trap",
    "href": "/api/configuration/management/snmp/trap",
    "last": "/api/configuration/management/snmp/trap",
    "next": null,
    "parent": "/api/configuration/management/snmp",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the address and protocol settings of the SNMP server.
  enabled boolean Set to true to send alerts to an SNMP server.
  version Top level item Contains the configuration settings for the server address, and the SNMP protocol.
Elements of version Type Description
selection     string

Defines the SNMP protocol to use. Possible values are:

  • 2c

    Configures version 2c of the SNMP protocol.

  • 3

    Configures version 3 of the SNMP protocol.

value     Top level item Contains the SNMP server address, and the protocol-specific settings.
  auth_method   string

Required parameter when using SNMP version 3. Configures encrypted communication with the SNMP server. Possible values are:

  • md5: Use MD5 encryption. The auth_password element must reference a valid password.

  • sha1: Use SHA1 encryption. The auth_password element must reference a valid password.

  auth_password   string

Required parameter when using SNMP version 3. References the password used for authenticating to the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  community   string

Must be used if version 2c of the SNMP protocol is configured.

The name of the SNMP community.

  encryption_method   string

Must be used if version 3 of the SNMP protocol is configured.

Configures encrypted communication with the SNMP server. Possible values are:

  • none: No encryption. The value of the encryption_password element must also be set to null.

  • aes: AES encryption. The encryption_password element must reference a valid password.

  • des: DES encryption. The encryption_password element must reference a valid password.

  encryption_password   string

Must be used if version 3 of the SNMP protocol is configured.

Set to null if the value of the encryption_method is set to none.

References the password used for encrypting the communication with the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  engine_id   string

Must be used if version 3 of the SNMP protocol is configured.

The Engine ID. Must be a a hexadecimal number at least 10 digits long (for example, 0x0123456789ABCDEF).

  server   top level item Contains the IP address of FQDN of the SNMP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The SNMP server address is provided as a fully qualified domain name.

  • ip

    The SNMP server address is provided as an IP address.

    value string The address of the SNMP server.
  username   string

Must be used if version 3 of the SNMP protocol is configured.

The username for sending SNMP traps.

Examples: 

Configure a server with the SNMP v2c protcol.

{
  "enabled": true,
  "version": {
    "selection": "2c",
    "value": {
      "community": "public",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      }
    }
  }
}

Configure a server with the SNMP v3 protocol, and MD5 authentication.

{
  "enabled": true,
  "version": {
    "selection": "3",
    "value": {
      "auth_method": "md5",
      "auth_password": {
        "key": "d21f3675-8dff-43c5-a982-17839390a6b3",
        "meta": {
          "href": "/api/configuration/passwords/d21f3675-8dff-43c5-a982-17839390a6b3"
        }
      },
      "encryption_method": "none",
      "encryption_password": null,
      "engine_id": "<0x0123456789ABCDEF>",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "username": "<username>"
    }
  }
}

Configure a server with the SNMP v3 protocol, SHA1 authentication, and AES-encrypted communication.

{
  "enabled": true,
  "version": {
    "selection": "3",
    "value": {
      "auth_method": "sha",
      "auth_password": {
        "key": "0f5f646d-d6e7-4a4a-bc66-ead670faff3f",
        "meta": {
          "href": "/api/configuration/passwords/0f5f646d-d6e7-4a4a-bc66-ead670faff3f"
        }
      },
      "encryption_method": "aes",
      "encryption_password": {
        "key": "6237d67a-b6b4-49e0-b0f6-6d68d0f08cc3",
        "meta": {
          "href": "/api/configuration/passwords/6237d67a-b6b4-49e0-b0f6-6d68d0f08cc3"
        }
      },
      "engine_id": "<0x0123456789ABCDEF>",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "username": "<username>"
    }
  }
}

Modify SNMP trap settings

To modify the address and protocol settings for the SNMP server, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the SNMP trap endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/snmp/trap endpoint. You can find a detailed description of the available parameters listed in SNMP trap.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.8. Local services — access for SNMP agents

External SNMP agents can query the basic status information of SCB. On this endpoint you can configure on which interfaces can the users access SCB, and optionally restrict the access to these interfaces, and configure authentication and encryption settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services/snmp_agent

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services/snmp_agent

Response

The following is a sample response received when listing the configuration options. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "access_restriction": {
            "enabled": false
        },
        "enabled": true,
        "listen": [
            {
                "address": {
                    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
                    "meta": {
                        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
                    }
                },
                "port": 161
            }
        ],
        "system_contact": "mycontact",
        "system_description": "mydescription",
        "system_location": "mylocation",
        "version_2c": {
            "community": "mycommunity",
            "enabled": true
        },
        "version_3": {
            "enabled": true,
            "users": [
                {
                    "auth_method": "sha",
                    "auth_password": {
                        "key": "5476940c-ba38-4002-96d4-cb09d6921c68",
                        "meta": {
                            "href": "/api/configuration/passwords/5476940c-ba38-4002-96d4-cb09d6921c68"
                        }
                    },
                    "encryption_method": "aes",
                    "encryption_password": {
                        "key": "99782a91-63de-4a5c-82ff-b82273894dc7",
                        "meta": {
                            "href": "/api/configuration/passwords/99782a91-63de-4a5c-82ff-b82273894dc7"
                        }
                    },
                    "username": "myusername"
                }
            ]
        }
    },
    "key": "snmp_agent",
    "meta": {
        "first": "/api/configuration/local_services/admin_web",
        "href": "/api/configuration/local_services/snmp_agent",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/ssh",
        "parent": "/api/configuration/local_services",
        "previous": "/api/configuration/local_services/postgresql",
        "transaction": "/api/transaction"
    }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options of the SNMP agent.
  access_restriction   JSON object Enables and configures limitations on the clients that can access the web interface, based on the IP address of the clients.
    allowed_from list The list of IP networks from where the administrators are permitted to access this management interface. To specify the IP addresses or networks, use the IPv4-Address/prefix format, for example, 10.40.0.0/16.
    enabled boolean Set it to true to restrict access to the specified client addresses.
  enabled   boolean Enables the SNMP server. If this option is set to False, SCB ignores every other option of this endpoint.
  listen   list Selects the network interface, IP address, and port where the clients can access the web interface.
    address JSON object

A reference to a configured network interface and IP address where this local service accepts connections. For example, if querying the interface /api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/ returns the following response:

{
    "body": {
        "interfaces": {
            "@order": [
                "ff7574025754b3df1647001"
            ],
            "ff7574025754b3df1647001": {
                "addresses": {
                    "1": "10.40.255.171/24",
                    "@order": [
                        "1"
                    ]
                },
                "name": "default",
                "vlantag": 0
            }
        },
        "name": "eth0",
        "speed": "auto"
    },
    "key": "nic1",
    "meta": {
        "first": "/api/configuration/network/nics/nic1",
        "href": "/api/configuration/network/nics/nic1",
        "last": "/api/configuration/network/nics/nic3",
        "next": "/api/configuration/network/nics/nic2",
        "parent": "/api/configuration/network/nics",
        "previous": null,
        "transaction": "/api/transaction"
    }
    }

Then the listening address of the local service is the following.

nic1.interfaces.ff7574025754b3df1647001.addresses.1

This is the format you have to use when configuring the address of the local service using REST:

"address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1"

When querying a local services endpoint, the response will contain a reference to the IP address of the interface in the following format:

"address": {
    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
    "meta": {
        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
    }
    },
    port integer

The port number where this local service accepts connections.

  system_contact   string Optional. For example, it can contain the contact information of the SCB administrator.
  system_description   string Optional. For example, it can contain information of the SCB host.
  system_description   string Optional. For example, it can contain the location of the SCB appliance.
  version_2c   JSON object

Enables and configures SNMP queries using the SNMP v2c protocol. You can have both the SNMP v2c and v3 protocols enabled at the same time. For example:

"version_2c": {
    "community": "mycommunity",
    "enabled": true
},
    community string Optional. Specifies the community to use.
    enabled boolean Optional. Enables SNMP queries using the SNMP v2c protocol.
  version_3   JSON object

Enables and configures SNMP queries using the SNMP v3 protocol. You can have both the SNMP v2c and v3 protocols enabled at the same time. You must configure an authentication method and a password, encryption is optional. For example:

"version_3": {
    "enabled": true,
    "users": [
        {
            "auth_method": "sha",
            "auth_password": {
                "key": "5476940c-ba38-4002-96d4-cb09d6921c68",
                "meta": {
                    "href": "/api/configuration/passwords/5476940c-ba38-4002-96d4-cb09d6921c68"
                }
            },
            "encryption_method": "aes",
            "encryption_password": {
                "key": "99782a91-63de-4a5c-82ff-b82273894dc7",
                "meta": {
                    "href": "/api/configuration/passwords/99782a91-63de-4a5c-82ff-b82273894dc7"
                }
            },
            "username": "myusername"
        }
    ]
}
Elements of version_3 Type Description
enabled   boolean Optional. Enables SNMP queries using the SNMP v2c protocol.
users   JSON object Contains the configuration parameters for the SNMP v3 protocol.
  auth_method string

Required parameter when using SNMP version 3. Configures encrypted communication with the SNMP server. Possible values are:

  • md5: Use MD5 encryption. The auth_password element must reference a valid password.

  • sha1: Use SHA1 encryption. The auth_password element must reference a valid password.

  auth_password string

Required parameter when using SNMP version 3. References the password used for authenticating to the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  encryption_method string

Configures encrypted communication with the SNMP server. Possible values are:

  • none: No encryption. The value of the encryption_password element must also be set to null.

  • aes: AES encryption. The encryption_password element must reference a valid password.

  • des: DES encryption. The encryption_password element must reference a valid password.

  encryption_password string

Set to null if the value of the encryption_method is set to none.

References the password used for encrypting the communication with the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  username string

The username for sending SNMP traps.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.9. Alerting

Contains the endpoints for configuring alerting on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/alerting

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists alerting configuration endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/alerting

Response

The following is a sample response received when listing alerting configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "system_alerts",
      "meta": {
        "href": "/api/configuration/alerting/system_alerts"
      }
    },
    {
      "key": "traffic_alerts",
      "meta": {
        "href": "/api/configuration/alerting/traffic_alerts"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/alerting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/datetime",
    "parent": "/api/configuration",
    "previous": "/api/configuration/aaa",
    "transaction": "/api/transaction"
  }
}
Element Description
system_alerts Configuration options for system-related alerts.
traffic_alerts Configuration options for traffic-related alerts.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.10. System alerts

Configuration options for sending system-related alerts.

E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.

SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.

URL

GET https://<IP-address-of-SCB>/api/configuration/alerting/system_alerts

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists configuration options for system-related alerts.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/alerting/system_alerts

Response

The following is a sample response received when listing configuration options for system-related alerts. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "xcbAlert": {
      "email": false,
      "snmp": false
    },
    "xcbArchiveFailed": {
      "email": false,
      "snmp": false
    },
    "xcbBackupFailed": {
      "email": false,
      "snmp": false
    },
    "xcbBruteForceAttempt": {
      "email": false,
      "snmp": false
    },
    "xcbConfigChange": {
      "email": false,
      "snmp": false
    },
    "xcbDBError": {
      "email": false,
      "snmp": false
    },
    "xcbDiskFull": {
      "email": false,
      "snmp": false
    },
    "xcbError": {
      "email": false,
      "snmp": false
    },
    "xcbFirmwareTainted": {
      "email": false,
      "snmp": false
    },
    "xcbHWError": {
      "email": false,
      "snmp": false
    },
    "xcbHaNodeChanged": {
      "email": false,
      "snmp": false
    },
    "xcbLicenseAlmostExpired": {
      "email": false,
      "snmp": false
    },
    "xcbLimitReached": {
      "email": false,
      "snmp": false
    },
    "xcbLoadAvgHigh": {
      "email": false,
      "snmp": false
    },
    "xcbLogin": {
      "email": false,
      "snmp": false
    },
    "xcbLoginFailure": {
      "email": false,
      "snmp": false
    },
    "xcbLogout": {
      "email": false,
      "snmp": false
    },
    "xcbRaidStatus": {
      "email": false,
      "snmp": false
    },
    "xcbSwapFull": {
      "email": false,
      "snmp": false
    },
    "xcbTimeSyncLost": {
      "email": false,
      "snmp": false
    },
    "xcbTimestampError": {
      "email": false,
      "snmp": false
    }
  },
  "key": "system_alerts",
  "meta": {
    "first": "/api/configuration/alerting/system_alerts",
    "href": "/api/configuration/alerting/system_alerts",
    "last": "/api/configuration/alerting/traffic_alerts",
    "next": "/api/configuration/alerting/traffic_alerts",
    "parent": "/api/configuration/alerting",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options for system-related alerts.
  xcbAlert   Top level item General alert.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbArchiveFailed   Top level item Data archiving failure.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbBackupFailed   Top level item Data and configuration backup failure.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbBruteForceAttempt   Top level item Too many successive failed login attempts.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbConfigChange   Top level item Configuration change.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbDBError   Top level item Database error occured.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbDiskFull   Top level item Disk utilization reached the percentage configured in the maximum_disk_utilization_ratio element of the api/configuration/management/monitoring endpoint.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbError   Top level item General error.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbFirmwareTainted   Top level item The firmware is tainted.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbHWError   Top level item Hardware error.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbHaNodeChanged   Top level item HA node state changed.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLicenseAlmostExpired   Top level item License expires soon.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLimitReached   Top level item License limit reached.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLoadAvgHigh   Top level item The average load exceeded any of the values configured in the maximum_load1, maximum_load5 or maximum_load15 elements of the api/configuration/management/monitoring endpoint.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLogin   Top level item Successful login.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLoginFailure   Top level item Failed login.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbLogout   Top level item Logout from the web configuration interface.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbRaidStatus   Top level item RAID status changed.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbSwapFull   Top level item The utilization of the swap exceeded the value configured in the maximum_swap_utilization_ratio element of the api/configuration/management/monitoring endpoint.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbTimeSyncLost   Top level item Time sync lost.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  xcbTimestampError   Top level item Time stamping error.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.

Modify a system-related alert

To enable or disable an alert, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/alerting/system_alerts endpoint. You can find a detailed description of the available parameters listed in System alerts.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

3.4.11. Traffic alerts

Configuration options for sending traffic-related alerts.

E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.

SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.

URL

GET https://<IP-address-of-SCB>/api/configuration/alerting/traffic_alerts

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options for traffic-related alerts..

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/alerting/traffic_alerts

Response

The following is a sample response received when listing the configuration options for traffic-related alerts. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "scbAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbChannelDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionDenied": {
      "email": false,
      "snmp": false
    },
    "scbConnectionFailed": {
      "email": false,
      "snmp": false
    },
    "scbConnectionTimedout": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreClosed": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreDecryptError": {
      "email": false,
      "snmp": false
    },
    "scbCredStoreUnlockFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthFailure": {
      "email": false,
      "snmp": false
    },
    "scbGWAuthSuccess": {
      "email": false,
      "snmp": false
    },
    "scbProtocolViolation": {
      "email": false,
      "snmp": false
    },
    "scbRealTimeAlert": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyLearned": {
      "email": false,
      "snmp": false
    },
    "scbSshHostKeyMismatch": {
      "email": false,
      "snmp": false
    },
    "scbUserMappingFailure": {
      "email": false,
      "snmp": false
    }
  },
  "key": "traffic_alerts",
  "meta": {
    "first": "/api/configuration/alerting/system_alerts",
    "href": "/api/configuration/alerting/traffic_alerts",
    "last": "/api/configuration/alerting/traffic_alerts",
    "next": null,
    "parent": "/api/configuration/alerting",
    "previous": "/api/configuration/alerting/system_alerts",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options for traffic-related alerts.
  scbAuthFailure   Top level item User authentication failed.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbAuthSuccess   Top level item Successful user authentication.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbChannelDenied   Top level item Channel opening denied.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbConnectionDenied   Top level item Connection denied.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbConnectionFailed   Top level item Connection to the server failed.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbConnectionTimedout   Top level item Connection timed out.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbCredStoreClosed   Top level item The requested credential store is closed.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbCredStoreDecryptError   Top level item Failure to decrypt a credential.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbCredStoreUnlockFailure   Top level item Failure to unlock the credential store.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbGWAuthFailure   Top level item The user failed to authenticate on the gateway.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbGWAuthSuccess   Top level item Successful authentication on the gateway.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbProtocolViolation   Top level item Protocol violation.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbRealTimeAlert   Top level item Real-time audit event detected.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbSshHostKeyLearned   Top level item New SSH hostkey learned.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbSshHostKeyMismatch   Top level item SSH host key mismatch.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.
  scbUserMappingFailure   Top level item User mapping failed on the gateway.
    email boolean Set to true to enable e-mail alerts.
    snmp boolean Set to true to enable SNMP alerts.

Modify a traffic-related alert

To enable or disable an alert, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/alerting/traffic_alerts endpoint. You can find a detailed description of the available parameters listed in Traffic alerts.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Chapter 4. User management and access control

4.1. User management and access control

The AAA endpoint contains the configuration endpoints for the authentication, authorization, and account (AAA) settings of the users who access SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the AAA configuration endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/

Response

The following is a sample response received when listing AAA configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "acls",
      "meta": {
        "href": "/api/configuration/aaa/acls"
      }
    },
    {
      "key": "local_database",
      "meta": {
        "href": "/api/configuration/aaa/local_database"
      }
    },
    {
      "key": "settings",
      "meta": {
        "href": "/api/configuration/aaa/settings"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/aaa",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/alerting",
    "parent": "/api/configuration",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Description
acls Access control settings for usergroups.
local_database Local users and usergroups.
settings Authentication and user database settings.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

4.2. Authentication and user database settings

Contains settings for authenticating to SCB. You can create a user database locally on SCB, or connect to an LDAP server to authenticate users. You can configure authentication with passwords, X.509 certificates, or against a RADIUS server.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/settings

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the authentication and user database settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/settings

Response

The following is a sample response received when listing authentication and user database settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "backend": {
      "cracklib_enabled": false,
      "expiration_days": 0,
      "minimum_password_strength": "good",
      "remember_previous_passwords": 10,
      "selection": "local"
    },
    "method": {
      "selection": "passwd"
    },
    "require_commitlog": false
  },
  "key": "settings",
  "meta": {
    "first": "/api/configuration/aaa/acls",
    "href": "/api/configuration/aaa/settings",
    "last": "/api/configuration/aaa/settings",
    "next": null,
    "parent": "/api/configuration/aaa",
    "previous": "/api/configuration/aaa/local_database",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the authentication settings.
  backend Top level item Settings for the user database (local or LDAP), and password policy.
  method Top level item Settings for the authentication method (password, RADIUS server, or X.509 certificate).
  require_commitlog boolean Set to true to request the user to write an explanation to every configuration change.
Elements of backend Type Description
selection     string

Defines the user database back-end. Possible values are:

  • ldap

    Use an LDAP server (AD or POSIX) for authentication.

  • local

    Use a local user database for authentication.

cracklib_enabled     boolean

Password setting. Set to false if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Set to true to test the strength of user passwords with simple dictionary attacks before they are committed.

Note

The strength of the password is determined by its entropy: the variety of numbers, letters, capital letters, and special characters used, not only by its length.

The Enable cracklib option executes some simple dictionary-based attacks to find weak passwords.

expiration_days     int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of days the user passwords are considered valid. Expired passwords must be changed upon login.

The 0 value means the passwords do not expire. The highest value you can configure is 365.

minimum_password_strength     string

Password setting. Set to disabled if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the required password strength for new passwords. Possible values are:

  • disabled

    Any password is accepted.

  • good

    Weak passwords are not accepted.

  • strong

    Only strong passwords are accepted.

remember_previous_passwords     int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of previous passwords to retain to prevent password reuse.

The 0 value means passwords can be reused.

base_dn     string

Must be used if the value of the selection element is set to ldap.

Name of the DN to be used as the base of the queries.

bind_dn     string

Name of the DN where SCB should bind to before accessing the database. Must be used if the value of the selection element is set to ldap.

Note
  • SCB accepts both pre-win2000-style and Win2003-style account names (User Principal Names), for example administrator@example.com is also accepted.

  • Do not use sAMAccountName, as the bind DN expects a CN.

bind_password     string

Must be used if the value of the selection element is set to ldap.

References the password SCB uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

Note

SCB accepts passwords that are not longer than 150 characters. The following special characters can be used: !"#$%&'()*+,-./:;<=>?@[\]^-`{|}

encryption     Top level item

Must be used if the value of the selection element is set to ldap.

Configuration settings for encrypting the communication between SCB and the LDAP server.

  client_authentication   Top level item

Must be used with the selection child element.

Configures the X.509 certificate SCB uses to authenticate on the LDAP server.

    enabled boolean

Must be used with the client-authentication parent element.

Set to true if the LDAP server requires mutual authentication.

    x509_identity string

Must be used if the enabled element is set to true.

References the identifier of the X.509 certificate stored on SCB. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  selection   string

Defines the type of encryption SCB uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    If you set the address using a domain name ("host": { "selection": "fqdn"), and you use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com), otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    Note

    TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

  server_certificate_check   Top level item

Must be used with the selection child element.

Configuration settings for verifying the LDAP server's certificate.

    enabled boolean

Must be used with the server_certificate_check parent element.

Set to true to verify the LDAP server's certificate using the certificate of a Certificate Authority (CA).

    server_certificate_ca string

Must be used if the enabled element is set to true.

The certificate of the CA.

memberof_attribute     string

The name of the user attribute (for example, in case of Active Directory: memberOf). Must be used if the value of the selection element is set to ldap, otherwise it is optional.

Configure this element if you have an LDAP schema where the user groups can only be determined from a user attribute that contains the group DNs.

Warning

Using this option significantly slows down logon to the SCB web interface if you have too many groups.

nested_groups     boolean

Must be used if the value of the selection element is set to ldap.

Set to true to use nested groups when querying the LDAP server

schema     Top level item

Must be used if the value of the selection element is set to ldap.

Schema settings for AD and POSIX servers.

  selection   string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

  member_uid_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the POSIX group membership.

  unique_member_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the GroupOfUniqueMemberships membership.

  username_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the username (user ID).

servers     Top level list

Must be used if the value of the selection element is set to ldap.

Contains the addresses and ports of the LDAP servers.

  host   Top level item Contains the address of the LDAP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

    value string

The address of the LDAP server.

  • If you set the address using an IP address ("selection": "ip"), use an IPv4 address.

  • If you set the address using a domain name ("host": { "selection": "fqdn"), and you use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com), otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

  port   int The port of the LDAP server.
Elements of method Type Description
selection     string

Configures the authentication method. Possible values are:

  • passwd: Use passwords for authentication.

  • radius: Configure authentication against a RADIUS server.

    Warning

    The challenge/response authentication methods is currently not supported. Other authentication methods (for example password, SecureID) should work.

  • x509: Use X.509 certificates for authentication.

servers     Top level list

RADIUS setting. Must be used if the value of the selection element is set to radius.

Contains the RADIUS server addresses and port numbers, and references the shared secrets.

  address   Top level item

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address and port number of the RADIUS server.

    selection string

RADIUS setting. Must be used if the value of the selection element is set to radius.

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The RADIUS server address is provided as a fully qualified domain name.

  • ip

    The RADIUS server address is provided as an IP address.

    value string

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address of the RADIUS server.

  port   int

RADIUS setting. Must be used if the value of the selection element is set to radius.

The port number of the RADIUS server.

  shared_secret   string

RADIUS setting. Must be used if the value of the selection element is set to radius.

References the identifier of the shared secret. You can view or modify the list of shared secrets at the /api/configuration/passwords/ endpoint.

To modify or add a shared secret, use the value of the returned key as the value of the shared_secret element, and remove any child elements (including the key).

admin_fallback     boolean

X.509 setting. Must be used if the value of the selection element is set to x509.

Set to true to allow the admin user to use password for login.

dn     string

X.509 setting. Must be used if the value of the selection element is set to x509.

X.509 DN field name of the username (case sensitive). In most cases, this value is either CN or UID.

trusted_ca     string

X.509 setting. Must be used if the value of the selection element is set to x509.

References the identifier of the trusted CA. You can view or modify the list of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

Local user database with password authentication

This example configures a local user database with a password policy to authenticate the users of SCB:

Note

SCB accepts passwords that are not longer than 150 characters. The following special characters can be used: !"#$%&'()*+,-./:;<=>?@[\]^-`{|}

Note

The strength of the password is determined by its entropy: the variety of numbers, letters, capital letters, and special characters used, not only by its length.

The Enable cracklib option executes some simple dictionary-based attacks to find weak passwords.

Note

Changes to the password policy do not affect existing passwords. However, setting password expiry will require every user to change their passwords after the expiry date, and the new passwords must comply with the strength requirements set in the password policy.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "good",
    "remember_previous_passwords": 10,
    "selection": "local"
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Local user database with RADIUS server

This example configures a local user database with a RADIUS server to authenticate the users of SCB. Note that the password-related elements have to be disabled, as the RADIUS server determines the password policy.

Warning

The challenge/response authentication methods is currently not supported. Other authentication methods (for example password, SecureID) should work.

Warning

After you commit this configuration, the SCB web interface will be available only after successfully authenticating to the RADIUS server. Note that the default admin account of SCB will be able to login normally, even if the RADIUS server is unaccessible.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "selection": "radius",
    "servers": [
      {
        "address": {
          "selection": "ip",
          "value": "<server-ip>"
        },
        "port": <port>,
        "shared_secret": "<id-of-the-password>"
      }
    ]
  },
  "require_commitlog": false
}

Local user database with X.509 certificates

This example configures a local user database with X.509 certificates to authenticate the users of SCB. Note that the password-related elements have to be disabled.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "admin_fallback": true,
    "dn": "<CN>",
    "selection": "x509",
    "trusted_ca": "<id-of-the-trusted-ca>"
  },
  "require_commitlog": false
}

POSIX LDAP server

Note
  • The admin user is available by default and has all privileges. It is not possible to delete this user.

  • Enabling LDAP authentication automatically disables the access of every local user except for admin. The admin user can login to SCB even if LDAP authentication is used.

  • SCB accepts both pre-win2000-style and Win2003-style account names (User Principal Names). User Principal Names (UPNs) consist of a username, the at (@) character, and a domain name, for example administrator@example.com.

  • For the username of SSH users, only valid UTF-8 strings are allowed.

  • The following characters cannot be used in usernames and group names: /\[]:;|=,+*)?<>@"

  • When using RADIUS authentication together with LDAP users, the users are authenticated to the RADIUS server, only their group memberships must be managed in LDAP. For details, see Procedure 5.5, Authenticating users to a RADIUS server in The Balabit Shell Control Box 4 F4 Administrator Guide.

Warning

A user can belong to a maximum of 10,000 groups, further groups are ignored.

Warning

By default, SCB uses nested groups when querying the LDAP server. Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large. In this case, disable the Enable nested groups option.

Note

You also have to configure the usergroups in SCB and possibly in your LDAP database. For details on using usergroups, see Section 5.7.4, How to use usergroups in The Balabit Shell Control Box 4 F4 Administrator Guide.

This example configures a POSIX LDAP server, communication between SCB and the LDAP server is not encrypted. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the POSIX server determines the password policy.

{
  "backend": {
    "base_dn": "<basedn>",
    "bind_dn": "<binddn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "selection": "disabled"
    },
    "memberof_attribute": "<user-attr-of-group-dns>",
    "nested_groups": true,
    "schema": {
      "member_uid_attribute": "<memberUid-attr>",
      "selection": "posix",
      "unique_member_attribute": "<uniqueMember-attr>",
      "username_attribute": "<uid-attr>"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Microsoft Active Directory server

Note
  • The admin user is available by default and has all privileges. It is not possible to delete this user.

  • Enabling LDAP authentication automatically disables the access of every local user except for admin. The admin user can login to SCB even if LDAP authentication is used.

  • SCB accepts both pre-win2000-style and Win2003-style account names (User Principal Names). User Principal Names (UPNs) consist of a username, the at (@) character, and a domain name, for example administrator@example.com.

  • For the username of SSH users, only valid UTF-8 strings are allowed.

  • The following characters cannot be used in usernames and group names: /\[]:;|=,+*)?<>@"

  • When using RADIUS authentication together with LDAP users, the users are authenticated to the RADIUS server, only their group memberships must be managed in LDAP. For details, see Procedure 5.5, Authenticating users to a RADIUS server in The Balabit Shell Control Box 4 F4 Administrator Guide.

Warning

A user can belong to a maximum of 10,000 groups, further groups are ignored.

Warning

By default, SCB uses nested groups when querying the LDAP server. Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large. In this case, disable the Enable nested groups option.

Note

You also have to configure the usergroups in SCB and possibly in your LDAP database. For details on using usergroups, see Section 5.7.4, How to use usergroups in The Balabit Shell Control Box 4 F4 Administrator Guide.

This example configures a Microsoft Active Directory server with mutual authentication, and SCB verifies the certificate of the server. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the AD server determines the password policy.

{
  "backend": {
    "base_dn": "<base-dn>",
    "bind_dn": "<bind-dn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "client_authentication": {
        "enabled": true,
        "x509_identity": "<id-of-the-cert>",
      "selection": "starttls",
      "server_certificate_check": {
        "enabled": true,
        "server_certificate_ca": "<cert>"
      }
    },
    "memberof_attribute": "<memberOf-attribute-name>",
    "nested_groups": true,
    "schema": {
      "selection": "ad"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Modify the authentication and user database settings

To modify the authentication and user database settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/settings endpoint. You can find a detailed description of the available parameters listed in Authentication and user database settings.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

4.3. Privileges of usergroups

This endpoint lists the usergroups configured on SCB, and the privileges (ACLs) of each group.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/acls

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the local users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/acls

Response

The following is a sample response received when querying the endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "body": [
        {
            "group": "basic-view",
            "objects": [
                "/special/basic"
            ],
            "permission": "read"
        },
        {
            "group": "basic-write",
            "objects": [
                "/special/basic"
            ],
            "permission": "write"
        },
        {
            "group": "auth-view",
            "objects": [
                "/special/auth"
            ],
            "permission": "read"
        },
        {
            "group": "auth-write",
            "objects": [
                "/special/auth"
            ],
            "permission": "write"
        },
        {
            "group": "search",
            "objects": [
                "/special/searchmenu"
            ],
            "permission": "read"
        },
        {
            "group": "changelog",
            "objects": [
                "/special/changelog"
            ],
            "permission": "read"
        },
        {
            "group": "policies-view",
            "objects": [
                "/special/pol"
            ],
            "permission": "read"
        },
        {
            "group": "policies-write",
            "objects": [
                "/special/pol"
            ],
            "permission": "write"
        },
        {
            "group": "ssh-view",
            "objects": [
                "/special/ssh"
            ],
            "permission": "read"
        },
        {
            "group": "ssh-write",
            "objects": [
                "/special/ssh"
            ],
            "permission": "write"
        },
        {
            "group": "rdp-view",
            "objects": [
                "/special/rdp"
            ],
            "permission": "read"
        },
        {
            "group": "rdp-write",
            "objects": [
                "/special/rdp"
            ],
            "permission": "write"
        },
        {
            "group": "telnet-view",
            "objects": [
                "/special/telnet"
            ],
            "permission": "read"
        },
        {
            "group": "telnet-write",
            "objects": [
                "/special/telnet"
            ],
            "permission": "write"
        },
        {
            "group": "vnc-view",
            "objects": [
                "/special/vnc"
            ],
            "permission": "read"
        },
        {
            "group": "vnc-write",
            "objects": [
                "/special/vnc"
            ],
            "permission": "write"
        },
        {
            "group": "indexing",
            "objects": [
                "/special/search/search",
                "/special/bap"
            ],
            "permission": "write"
        },
        {
            "group": "ica-view",
            "objects": [
                "/special/ica"
            ],
            "permission": "read"
        },
        {
            "group": "ica-write",
            "objects": [
                "/special/ica"
            ],
            "permission": "write"
        },
        {
            "group": "api",
            "objects": [
                "/special/rpcapi"
            ],
            "permission": "write"
        },
        {
            "group": "http-view",
            "objects": [
                "/special/http"
            ],
            "permission": "read"
        },
        {
            "group": "http-write",
            "objects": [
                "/special/http"
            ],
            "permission": "write"
        },
        {
            "group": "indexer-view",
            "objects": [
                "/special/indexer"
            ],
            "permission": "read"
        },
        {
            "group": "indexer-write",
            "objects": [
                "/special/indexer"
            ],
            "permission": "write"
        }
    ],
    "key": "acls",
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/acls",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/local_database",
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Element Type Description
body   Top level element (JSON object) Contains the properties of the user.
  group string The name of the usergroup.
  objects list The list of privileges that the group has access to.
  permission read | write The type of the permission. The group needs write access to configure an object, or to perform certain actions.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

4.4. Manage users and usergroups locally on SCB

Contains the endpoints for managing users and usergroups locally on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints of the local database.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database

Response

The following is a sample response received when listing the endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "groups",
            "meta": {
                "href": "/api/configuration/aaa/local_database/groups"
            }
        },
        {
            "key": "users",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/local_database",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/settings",
        "parent": "/api/configuration/aaa",
        "previous": "/api/configuration/aaa/acls",
        "transaction": "/api/transaction"
    }
}
Element Description
groups Endpoint that contains local usergroups.
users Endpoint that contains local usernames.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

4.5. Manage usergroups locally on SCB

Contains the local usergroups of SCB. You can use local groups to control the privileges of SCB local and LDAP users — who can view and configure what. You can edit the group memberships here as well.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the local usergroups.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups

Response

The following is a sample response received when querying a particular usergroup endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "members": [],
        "name": "http-write"
    },
    "key": "ca2dc85730ca082ee6b5c8",
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups/224696054489c27f6c5710",
        "href": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5c8",
        "last": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5f8",
        "next": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1f9",
        "parent": "/api/configuration/aaa/local_database/groups",
        "previous": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
        "transaction": "/api/transaction"
    }
}
Element Type Description
body   Top level element (JSON object) Contains the properties of the usergroup.
  members list Lists the names of the users belonging to the group.
  name string The name of the group.
key   string Top level element, contains the ID of the endpoint.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Section 2.3, Open a transaction).

Add new local usergroup

To create a new local usergroup, you have to POST the name and members of the group as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups endpoint. For details, see Section 2.9.2, Create a new object.

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create a new usergroup. POST the name of the group and the list of member accounts as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups endpoint. The body of the POST request should be the following. Note that you must refer to existing user accounts, and use their reference IDs, not their usernames.

    {
        "name": "new-userggroup",
        "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]
    }

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups --data "{"name": "new-usergroup", "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]}"

    If the POST request is successful, the response includes a reference ID for the usergroup object.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Delete usergroup

To delete a usergroup, you have to:

  1. Open a transaction (for details, see Section 2.3, Open a transaction).

  2. DELETE the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Section 2.9.1, Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

    {
        "meta": {
            "href": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
            "parent": "/api/configuration/aaa/local_database/groups"
        }
    }
  3. Commit your changes to actually delete the object from SCB (for details, see Section 2.4, Commit a transaction).

4.6. Manage users locally on SCB

Contains the local users of SCB. You can use local users and groups to control the privileges of SCB local and LDAP users — who can view and configure what.

Note

The admin user is available by default and has all possible privileges. It is not possible to delete this user.

Local users cannot be managed when LDAP authentication is used. When LDAP authentication is enabled, the accounts of local users is disabled, but they are not deleted,

When using RADIUS authentication together with local users, the users are authenticated to the RADIUS server, only their group memberships must be managed locally on SCB.

For details, see Section 4.2, Authentication and user database settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the local users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users

The following command displays the parameters of a specific user.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<ID-of-the-user>

Response

The following is a sample response received when querying the list of users. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "103640099357f3b14f0529a",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a"
            }
        },
        {
            "key": "46785097158061f46c63d0",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups",
        "href": "/api/configuration/aaa/local_database/users",
        "last": "/api/configuration/aaa/local_database/users",
        "next": null,
        "parent": "/api/configuration/aaa/local_database",
        "previous": "/api/configuration/aaa/local_database/groups",
        "transaction": "/api/transaction"
    }
}

The following is a sample response received when querying a specific user.

{
    "body": {
        "name": "testuser",
        "password": {
            "key": "8f84d7d1-9de1-429a-a7a7-c33a61cc7419",
            "meta": {
                "href": "/api/configuration/passwords/8f84d7d1-9de1-429a-a7a7-c33a61cc7419"
            }
        },
        "password_created": 1476796261
    },
    "key": "46785097158061f46c63d0",
    "meta": {
        "first": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "last": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "next": null,
        "parent": "/api/configuration/aaa/local_database/users",
        "previous": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "transaction": "/api/transaction"
    }
Element Type Description
body   Top level element (JSON object) Contains the properties of the user.
  name string The username of the user account.
  password reference A reference to a password object. To create or update passwords, see Section 5.3, Passwords stored on SCB.
  password_created integer The date when the password of the account was changed in UNIX timestamp format (for example, 1476796261).
key   string Top level element, contains the ID of the user.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
400 SemanticError You tried to reuse a password object. You can use a password object for only one purpose, that is, you cannot reference a password object twice.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Section 2.3, Open a transaction).

Add new local user

To create a new local user account, you have to POST the username and the reference ID of the password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users endpoint. For details, see Section 2.9.2, Create a new object.

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create a new password object. SCB returns the reference ID of the password. For details, see Section 5.3, Passwords stored on SCB.

  3. Create a new user account. POST the username and the reference ID of the password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users endpoint. The body of the POST request should be the following.

    {
        "name": "new-user",
        "password": "<value-of-the-key-attribute-from-the-previous-step>"
    }

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users --data "{"name": "new-user", "password": "<value-of-the-key-attribute-from-the-previous-step>"}"

    If the POST request is successful, the response includes a reference ID for the user object.

  4. Commit your changes. For details, see Section 2.4, Commit a transaction.

Change password for a local user

To change the password of a user, you have to create a new password, then PUT the username and the reference ID of the new password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> endpoint.

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create a new password object. SCB returns the reference ID of the password. For details, see Section 5.3, Passwords stored on SCB.

  3. Update the user account. PUT the username and the reference ID of the new password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> endpoint. The body of the PUT request should be the following.

    {
        "name": "username",
        "password": "<value-of-the-key-attribute-from-the-previous-step>"
    }

    For example:

    curl -X PUT -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> --data "{"name": "new-user", "password": "<value-of-the-key-attribute-from-the-previous-step>"}"

    If the request is successful, the response includes the reference ID for the user object.

  4. Commit your changes. For details, see Section 2.4, Commit a transaction.

Delete user

To delete a user, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. DELETE the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<ID-of-the-user> endpoint. For details, see Section 2.9.1, Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

    {
        "meta": {
            "href": "/api/configuration/aaa/local_database/users/b080b1ba546232548bb1a9",
            "parent": "/api/configuration/aaa/local_database/users"
        }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Chapter 5. Managing SCB

5.1. Troubleshooting options

Configures debug logging and the retention time of core dump files.

  • Debug logging increases the log level of the non-network-related events, adding the commands executed by the SCB web interface to the log.

  • SCB automatically generates core dump files if an important software component of the system crashes. These core dump files can be of great help to the Balabit Support Team to identify problems. To download the generated core dump files, navigate to Basic Settings > Troubleshooting > Core files on the web interface of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/troubleshooting

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command queries the troubleshooting settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/troubleshooting

Response

The following is a sample response received. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "core_files": {
      "retention_days": 14
    },
    "debug_logging": {
      "enabled": true
    }
  },
  "key": "troubleshooting",
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/troubleshooting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/vnc",
    "parent": "/api/configuration",
    "previous": "/api/configuration/telnet",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the troubleshooting settings.
  core_files   Top level item Contains the settings for core dump file retention.
    retention_days int Retention time for core files, in days.
  debug_logging   Top level item Settings for debug logging.
    enabled boolean Set to true to increase the log level of the non-network-related events, adding the commands executed by the SCB web interface to the log.

Modify troubleshooting settings

To modify troubleshooting settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the troubleshooting options. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/troubleshooting endpoint. You can find a detailed description of the available parameters listed in Troubleshooting.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

5.2. Internal certificates

This endpoint references the certificates of SCB's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web interface.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/certificates

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the internal certificates of SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/certificates

Response

The following is a sample response received when listing the internal certificates of SCB. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "ca": {
      "selection": "identity",
      "x509_identity": {
        "key": "fbd684e1-e1ac-4f34-ad25-86c560c51e24",
        "meta": {
          "href": "/api/configuration/x509/fbd684e1-e1ac-4f34-ad25-86c560c51e24"
        }
      }
    },
    "server": {
      "key": "fd1c73e8-bcb8-4d13-991f-722f492dc074",
      "meta": {
        "href": "/api/configuration/x509/fd1c73e8-bcb8-4d13-991f-722f492dc074"
      }
    },
    "tsa": {
      "key": "20e72ede-78ef-460a-b843-68a35d994142",
      "meta": {
        "href": "/api/configuration/x509/20e72ede-78ef-460a-b843-68a35d994142"
      }
    }
  },
  "key": "certificates",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/certificates",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/disk_fillup_prevention",
    "parent": "/api/configuration/management",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string The ID of the endpoint.
body     Top level element (string) Contains the internal certificates of SCB.
  ca   Top level item Contains the certificate of SCB's internal Certificate Authority.
    selection string Must be set to identity.
    x509_identity string

References the certificate of SCB's internal Certificate Authority. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). For details, see Section 5.5, Certificates stored on SCB.

  server   string

References the SSL certificate of SCB's web interface. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). For details, see Section 5.5, Certificates stored on SCB.

  tsa   string

References the certificate of SCB's internal Timestamping Authority. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). For details, see Section 5.5, Certificates stored on SCB.

Modify a certificate

To modify a certificate, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create a CA. Have the value of the key element of a valid X.509 CA certificate stored on SCB.

  3. Modify the JSON object of the endpoint. Use the X.509 certificate's key as the value of the ca element. You can find a detailed description of the available parameters listed in Internal certificates. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/certificates endpoint.

  4. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

5.3. Passwords stored on SCB

To create a new password, you have to POST the password or its hash as a JSON object to the https://<IP-address-of-SCB>/api/passwords endpoint. For details, see Section 2.9.2, Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Password parameters. The response to a successful POST message is a JSON object that includes the reference ID of the created password in its key attribute. You can reference this ID in other parts of the configuration, for example, to set the password of a user account. Note that you can use a password object for only one purpose, that is, you cannot reference a password object twice.

URL

POST https://<IP-address-of-SCB>/api/configuration/passwords
  • Note that the GET method is not permitted on this endpoint, you cannot list the existing passwords. However, if you know the reference ID of a password, you can display its properties:

    GET https://<IP-address-of-SCB>/api/configuration/passwords/<reference-ID-of-the-password;>
  • You cannot directly delete or modify a password, the DELETE and PUT methods are not permitted on password objects. To update a password, create a new one, then update the object that uses the old password to reference the new password.

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command creates a new password object.

curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/passwords --data "{"plain": "newpassword"}"

If you do not want to include the actual password in the request, the SHA-256 hash of the password is enough:

curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/passwords --data "{"hash": "$6$rounds=5000$If20/EFyQ4dW3dg/$xrECLfXgZlC2Xr1s257E2aZen42fM7R.sOGG9pkPy1x5ORTx6j03oPWexVlB3f5wnaZOQCBF.NjlDgyg2WEe./"}
Element Type Description
hash string Must contain the SHA-256 hash of the password to be created, for example, "hash": "ddec437eeb1da25a146a24c432d1165bc646daa7fecc6aa14c636265c83caa14". The request must contain at least the hash or the plain attribute.
nthash string Optional. Contains the NT-HASH of the password to be created, for example, "nthash": "2c01a73ad9e597f6eab0d072ed74616c"
plain string Contains the password in plain-text format, for example, "plain": "mypassword". The request must contain at least the hash or the plain attribute.

Response

The response to a successful POST message is a JSON object that includes the reference ID of the created password in its key attribute. For details of the meta object, see Section 1.1, Message format.

{
    "key": "faa96916-c85e-46ff-8697-f4cc5e596e7f",
    "meta": {
        "href": "/api/configuration/passwords/faa96916-c85e-46ff-8697-f4cc5e596e7f",
        "parent": "/api/configuration/passwords",
        "transaction": "/api/transaction"
    }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
405 GetNotAllowed The method GET is not allowed for this endpoint. You cannot list the existing passwords.
405 PutNotAllowed The method PUT is not allowed for this endpoint. You cannot modify an existing password. For details, see Section Modify or delete password.

Modify or delete password

You cannot directly delete or modify a password, the DELETE and PUT methods are not permitted on password objects. To update a password, create a new one, then update the object that uses the old password to reference the new password. After you commit the transaction, SCB will automatically delete the old password.

5.4. Private keys stored on SCB

To create a new private key, you have to POST the private key as a JSON object to the https://<IP-address-of-SCB>/api/private_keys endpoint. For details, see Section 2.9.2, Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Private key parameters. The response to a successful POST message is a JSON object that includes the reference ID of the created private key in its key attribute. You can reference this ID in other parts of the configuration. Note that you can use a private-key object for only one purpose, that is, you cannot reference one object twice.

URL

POST https://<IP-address-of-SCB>/api/configuration/private_keys
  • Note that the GET method is not permitted on this endpoint, you cannot list the existing private keys. However, if you know the reference ID of a private key, you can display its properties:

    GET https://<IP-address-of-SCB>/api/configuration/private_keys/<reference-ID-of-the-private-key;>
  • You cannot directly delete or modify a private key, the DELETE and PUT methods are not permitted on private key objects. To update a private key, create a new one, then update the object that uses the old private key to reference the new private key.

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command creates a new private key object. Note the following requirements:

  • The key must be in PKCS-1 PEM format.

  • Encrypted private keys are not supported.

  • The body of the POST message must be the private key as a single line enclosed, enclosed in double-quotes.

  • Replace line-breaks in the PEM file with \n

curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/private_keys --data "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----\n"

Querying a specific key returns the following information about the key:

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/private_keys/<reference-ID-of-the-private-key;>
Element Type Description
public-key-fingerprint   string The fingerprint of the public key that matches the private key.
  digest string The fingerprint of the key, for example ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e
  hash_algorithm string The hash algorithm used to create the fingerprint, for example, sha256.
type string The type of the private key. Must be rsa  

Response

The response to a successful POST message is a JSON object that includes the reference ID of the created public key in its key attribute. For details of the meta object, see Section 1.1, Message format.

{
    "key": "faa96916-c85e-46ff-8697-f4cc5e596e7f",
    "meta": {
        "href": "/api/configuration/private_keys/faa96916-c85e-46ff-8697-f4cc5e596e7f",
        "parent": "/api/configuration/private_keys",
        "transaction": "/api/transaction"
    }
}

The response to querying a specific key is a JSON object that includes the parameters of the key, for example:

{
    "body": {
        "public-key-fingerprint": {
            "digest": "ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e",
            "hash_algorithm": "md5"
        },
        "type": "rsa"
    },
    "key": "6c4d1116-d79d-475b-bb37-9f844f085c14",
    "meta": {
        "first": "/api/configuration/private_keys/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "href": "/api/configuration/private_keys/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "last": "/api/configuration/private_keys/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "next": null,
        "parent": "/api/configuration/private_keys",
        "previous": "/api/configuration/private_keys/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "transaction": "/api/transaction"
    }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 SyntacticError Syntax error: Could not load PEM key: Unsupported private key format, only PKCS-1 is supported. Encrypted private keys are not supported.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
405 GetNotAllowed The method GET is not allowed for this endpoint. You cannot list the existing private keys.
405 PutNotAllowed The method PUT is not allowed for this endpoint. You cannot modify an existing private keys. For details, see Section Modify or delete private key.

Modify or delete private key

You cannot directly delete or modify a private key, the DELETE and PUT methods are not permitted on private key objects. To update a private key, create a new one, then update the object that uses the old private key to reference the new private key. After you commit the transaction, SCB will automatically delete the old private key.

5.5. Certificates stored on SCB

To create a new certificate, you have to POST the certificate and its private key as a JSON object to the https://<IP-address-of-SCB>/api/x509 endpoint. For details, see Section 2.9.2, Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Creating a new X.509 certificate — parameters. The response to a successful POST message is a JSON object that includes the reference ID of the created certificate in its key attribute. You can reference this ID in other parts of the configuration. Note that you can use a certificate object for only one purpose, that is, you cannot reference one object twice.

URL

POST https://<IP-address-of-SCB>/api/configuration/x509
  • Note that the GET method is not permitted on this endpoint, you cannot list the existing certificates. However, if you know the reference ID of a certificate, you can display its properties:

    GET https://<IP-address-of-SCB>/api/configuration/x509/<reference-ID-of-the-private-key;>
  • You cannot directly delete or modify a certificate, the DELETE and PUT methods are not permitted on certificate objects. To update a certificate, create a new one, then update the object that uses the old certificate to reference the new certificate.

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command creates a new certificate object. Note the following requirements:

  • The key must be in PKCS-1 PEM format.

  • You need the certificate and the private key as well.

  • Encrypted private keys are not supported.

  • The attributes of the POST message that contain the certificate and the private key must be a single line, enclosed in double-quotes.

  • Replace line-breaks in the PEM certificate with \n

  • The certificate and the certificate chain must be valid, SCB will reject invalid certificates and invalid certificate chains.

curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/x509 --data "{"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----\n"}"

The body should be:

{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----",
    "issuer_chain": []
}
Element Type Description
certificate   string The certificate in PKCS-1 PEM format (replace line-breaks with \n). For example: -----BEGIN CERTIFICATE-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END CERTIFICATE-----
  private_key string The private key of the certificate, without encryption or password protection (replace line-breaks with \n). For example: -----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----
  issuer_chain list A comma-separated list of the Certificate Authority (CA) certificates that can be used to validate the uploaded certificate.

Querying a specific key returns the following information about the key:

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/x509/<reference-ID-of-the-private-key;>
Element Type Description
fingerprint   string The fingerprint of the certificate.
  digest string The fingerprint of the certificate, for example ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e
  hash_algorithm string The hash algorithm used to create the fingerprint, for example, sha256.
subject string The subject string of the certificate.  

Response

The response to a successful POST message is a JSON object that includes the reference ID of the created certificate in its key attribute. For details of the meta object, see Section 1.1, Message format.

{
    "key": "faa96916-c85e-46ff-8697-f4cc5e596e7f",
    "meta": {
        "href": "/api/configuration/x509/faa96916-c85e-46ff-8697-f4cc5e596e7f",
        "parent": "/api/configuration/x509",
        "transaction": "/api/transaction"
    }
}

The response to querying a specific certificate is a JSON object that includes the parameters of the certificate, for example:

{
    "body": {
        "fingerprint": {
            "digest": "ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e",
            "hash_algorithm": "md5"
        },
        "subject": "C=RO/ST=State/L=Locality/O=Organization/OU=OrganizationalUnit/CN=example.com/emailAddress=root@example.com"
    },
    "key": "6c4d1116-d79d-475b-bb37-9f844f085c14",
    "meta": {
        "first": "/api/configuration/x509/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "href": "/api/configuration/x509/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "last": "/api/configuration/x509/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "next": null,
        "parent": "/api/configuration/x509",
        "previous": "/api/configuration/x509/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "transaction": "/api/transaction"
    }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 SyntacticError Syntax error: Could not load PEM key: Unsupported private key format, only PKCS-1 is supported. Encrypted private keys are not supported.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
405 GetNotAllowed The method GET is not allowed for this endpoint. You cannot list the existing certificates.
405 PutNotAllowed The method PUT is not allowed for this endpoint. You cannot modify an existing certificate. For details, see Section Modify or delete certificate.

Modify or delete certificate

You cannot directly delete or modify a certificate, the DELETE and PUT methods are not permitted on certificate objects. To update a certificate, create a new one, then update the object that uses the old certificate to reference the new certificate. After you commit the transaction, SCB will automatically delete the old certificate.

5.6. Local services — enabling SSH access to the SCB host

Exclusively for troubleshooting purposes, you can access the SCB host using SSH. Completing the Welcome Wizard automatically disables SSH access to SCB. Re-enabling it allows you to connect remotely to the SCB host and login using the root user. The password of the root user is the one you provided in the Welcome Wizard.

Warning

Accessing the SCB host directly using SSH is not recommended or supported, except for troubleshooting purposes. In such case, the Balabit Support Team will give you exact instructions on what to do to solve the problem.

For security reasons, disable SSH access to SCB when it is not needed. For details, see Procedure 6.5.2, Enabling SSH access to the SCB host in The Balabit Shell Control Box 4 F4 Administrator Guide.

The following encryption algorithms are configured on the local SSH service of SCB:

  • Key exchange (KEX) algorithms:

    diffie-hellman-group-exchange-sha256
  • Ciphers:

    aes256-ctr,aes128-ctr
  • Message authentication codes:

    hmac-sha2-512,hmac-sha2-256

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services/ssh

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services/ssh

Response

The following is a sample response received when listing the configuration options. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "access_restriction": {
            "allowed_from": [
                "10.40.0.48/24"
            ],
            "enabled": true
        },
        "allow_password_auth": true,
        "bruteforce_protection": true,
        "enabled": true,
        "listen": [
            {
                "address": {
                    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
                    "meta": {
                        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
                    }
                },
                "port": 23
            }
        ],
        "public_keys": [
            {
                "selection": "rsa",
                "value": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDTnisLCjZ3vONMXqFBIdvpZ0BY73+GdHpgoaL8YsydxJBsYg9dYTDzVVtYFVvdCVzBdcwCjyOuPwtZoYU3pLEFQ7OVoDUDPmVnl6idS/6tB2m89I5zdc02xUeCWTBpTGoOhNtc+YDmxPGZ1FQIpXCw0MT91jviWm3JydDd5YKINwvdTh8zsRT/702ZD9uZslwkQA/b2B9/hidCAkQkvs5H1B3o4laTd0JE9k90N+qbaQjVvoInr+jdXaWvrScwFVxZhb7Q1LvUL6oxW889bOWFMSa+/mnENarw6rpwfk9Ayi5uQQ2imY/tSnfgbS2RvIa1sKwUsJasDqN2lo/DuhON"
            }
        ]
    },
    "key": "ssh",
    "meta": {
        "first": "/api/configuration/local_services/admin_web",
        "href": "/api/configuration/local_services/ssh",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/user_web",
        "parent": "/api/configuration/local_services",
        "previous": "/api/configuration/local_services/snmp_agent",
        "transaction": "/api/transaction"
    }
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options of the SSH server.
  access_restriction   JSON object Enables and configures limitations on the clients that can access the web interface, based on the IP address of the clients.
    allowed_from list The list of IP networks from where the administrators are permitted to access this management interface. To specify the IP addresses or networks, use the IPv4-Address/prefix format, for example, 10.40.0.0/16.
    enabled boolean Set it to true to restrict access to the specified client addresses.
  allow_password_auth   boolean Enables password-based authentication, so administrators can remotely login to SCB. If this option is set to False, SCB ignores every other option of this endpoint.
  bruteforce_protection   boolean Enables protection against brute-force attacks by denying access after failed login attempts for increasingly longer period. Enabled by default.
  enabled   boolean Enables the SSH server, so administrators can remotely login to SCB. If this option is set to False, SCB ignores every other option of this endpoint.
  listen   list Selects the network interface, IP address, and port where the clients can access the web interface.
    address JSON object

A reference to a configured network interface and IP address where this local service accepts connections. For example, if querying the interface /api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/ returns the following response:

{
    "body": {
        "interfaces": {
            "@order": [
                "ff7574025754b3df1647001"
            ],
            "ff7574025754b3df1647001": {
                "addresses": {
                    "1": "10.40.255.171/24",
                    "@order": [
                        "1"
                    ]
                },
                "name": "default",
                "vlantag": 0
            }
        },
        "name": "eth0",
        "speed": "auto"
    },
    "key": "nic1",
    "meta": {
        "first": "/api/configuration/network/nics/nic1",
        "href": "/api/configuration/network/nics/nic1",
        "last": "/api/configuration/network/nics/nic3",
        "next": "/api/configuration/network/nics/nic2",
        "parent": "/api/configuration/network/nics",
        "previous": null,
        "transaction": "/api/transaction"
    }
    }

Then the listening address of the local service is the following.

nic1.interfaces.ff7574025754b3df1647001.addresses.1

This is the format you have to use when configuring the address of the local service using REST:

"address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1"

When querying a local services endpoint, the response will contain a reference to the IP address of the interface in the following format:

"address": {
    "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1",
    "meta": {
        "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1"
    }
    },
    port integer

The port number where this local service accepts connections.

  public_keys   list

Lists the public keys that can be used to authenticate on SCB. For example:

"public_keys": [
            {
                "selection": "rsa",
                "value": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDTnisLCjZ3vONMXqFBIdvpZ0BY73+GdHpgoaL8YsydxJBsYg9dYTDzVVtYFVvdCVzBdcwCjyOuPwtZoYU3pLEFQ7OVoDUDPmVnl6idS/6tB2m89I5zdc02xUeCWTBpTGoOhNtc+YDmxPGZ1FQIpXCw0MT91jviWm3JydDd5YKINwvdTh8zsRT/702ZD9uZslwkQA/b2B9/hidCAkQkvs5H1B3o4laTd0JE9k90N+qbaQjVvoInr+jdXaWvrScwFVxZhb7Q1LvUL6oxW889bOWFMSa+/mnENarw6rpwfk9Ayi5uQQ2imY/tSnfgbS2RvIa1sKwUsJasDqN2lo/DuhON"
            }
        ]

Balabit recommends using 2048-bit RSA keys (or stronger).

    selection rsa

The type of the public key. Must be rsa.

    value string

The public key itself.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

5.7. RPC API

The SCB RPC API allows you to access, query, and manage SCB from remote applications. You can access the API using the Simple Object Access Protocol (SOAP) protocol over HTTPS, meaning that you can use any programming language that has access to a SOAP client to integrate SCB to your environment.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/soap

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the RPC API settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/soap

Response

The following is a sample response received when listing the RPC API settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "enabled": true
  },
  "key": "soap",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/soap",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/syslog",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/snmp",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the RPC API configuration options.
  enabled boolean Set to true to enable the RPC API.

Modify RPC API settings

To modify the RPC API settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/soap endpoint. You can find a detailed description of the available parameters listed in RPC API.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Chapter 6. General connection settings

6.1. Channel policy

The channel policy lists the channels (for example, terminal session and SCP in SSH, Drawing, Clipboard in RDP) that can be used in a connection. The channel policy can further restrict access to each channel based on the IP address of the client or the server, a user list, user group, or a time policy. For example, all clients may access the servers defined in a connection via SSH terminal, but the channel policy may restrict SCP access only to a single client. The policies set in the channel policy are checked when the user attempts to open a particular channel type in the connection.

Channel policies are protocol specific. To list the available Channel policies for a protocol, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/<http|ica|rdp|ssh|telnet|vnc>/channel_policies

The following sections detail the properties of Channel policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/<http|ica|rdp|ssh|telnet|vnc>/channel_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific RDP Channel policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/<rdp>/channel_policies/<object-id>

Response

The following is a sample response received, showing the properties of Channel policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "name": "terminal-only",
    "rules": [
      {
        "actions": {
          "audit": true,
          "content_policy": null,
          "four_eyes": false,
          "ids": false
        },
        "allowed_for": {
          "clients": [],
          "gateway_groups": [],
          "remote_groups": [],
          "servers": [],
          "time_policy": {
            "key": "-100",
            "meta": {
              "href": "/api/configuration/policies/time_policies/-100"
            }
          }
        },
        "channel": "#drawing"
      },
      {
        "actions": {
          "audit": true,
          "four_eyes": false,
          "ids": false
        },
        "allowed_for": {
          "clients": [],
          "gateway_groups": [],
          "remote_groups": [],
          "servers": [],
          "time_policy": {
            "key": "-100",
            "meta": {
              "href": "/api/configuration/policies/time_policies/-100"
            }
          }
        },
        "channel": "cliprdr"
      }
    ]
  }
}
Element Type Description
name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
rules   list of JSON objects Top level element, contains the configuration properties of the object.
  actions JSON object The actions that SCB performs for the channel, for example, recording the traffic into an audit trail.
  allowed_for JSON object Specifies the access control rules of the channel, for example, permitted target IP addresses or usergroups.
  channel string

The type of the channel. Note that channels are protocol specific, and different type of channels can have different parameters.

For example:

"channel": "#drawing",
Element Type Description
actions   JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  audit boolean

Set to true to record the activities of the channel into audit trails. Possible values: true or false

  content_policy JSON object

Specifies the Content policy to use in the channel, otherwise its value is null (which is the default). For details on Content policies, see Section 6.4, Real-time content monitoring with Content Policies For example:

"content_policy": {
"key": "<object-id>",
}
  four_eyes boolean

Set to true to require four-eyes authorization to access the channel. For details, see Section 18.3, Configuring 4-eyes authorization in The Balabit Shell Control Box 4 F4 Administrator Guide. Possible values: true or false

Element Type Description
allowed_for   JSON object Specifies the access control rules of the channel.
  clients list

To restrict the availability of the channel only to certain clients, list the IP address or network of the clients allowed to use this the channel. For IPv6 addresses, use the canonized format of the address. For example:

"clients": [
  "192.168.1.1/24",
  "2001:db8:85a3::8a2e:0:0/32"
]
  gateway_groups list

You can control channel access during gateway authentication with blacklists or whitelists of user groups. You can use local user lists on SCB, or LDAP groups.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

For example:

"gateway_groups": ["group1", "group2"],

To configure local user lists, see Section 6.10, User lists.

  remote_groups list

You can control channel access during authentication to the remote server with blacklists or whitelists of user groups. You can use local user lists on SCB, or LDAP groups.

For example:

"remote_groups": ["group1", "group2"],

To configure local user lists, see Section 6.10, User lists.

  servers list

To restrict the availability of the channel only to certain servers, list the IP address or network of the servers that your clients are allowed to access using this the channel. For IPv6 addresses, use the canonized format of the address. For example:

"servers": [
  "192.168.1.1/24",
  "2001:db8:85a3::8a2e:0:0/32"
]
  time_policy JSON object

Specifies the Time policy to use in the channel. If you do not want to restrict access, use the default 7x24 policy-100. For details on Time policies, see Section 6.7, Time policy. For example:

"time_policy": {
  "key": "-100",
}

6.2. Policies

List of endpoints for configuring policies and settings that can be referenced when configuring connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies

Response

The following is a sample response received when listing the available configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "audit_policies",
      "meta": {
        "href": "/api/configuration/policies/audit_policies"
      }
    },
    {
      "key": "content_policies",
      "meta": {
        "href": "/api/configuration/policies/content_policies"
      }
    },
    {
      "key": "credentialstores",
      "meta": {
        "href": "/api/configuration/policies/credentialstores"
      }
    },
    {
      "key": "indexing",
      "meta": {
        "href": "/api/configuration/policies/indexing"
      }
    },
    {
      "key": "ldap_servers",
      "meta": {
        "href": "/api/configuration/policies/ldap_servers"
      }
    },
    {
      "key": "signing_cas",
      "meta": {
        "href": "/api/configuration/policies/signing_cas"
      }
    },
    {
      "key": "ticketing_policies",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies"
      }
    },
    {
      "key": "time_policies",
      "meta": {
        "href": "/api/configuration/policies/time_policies"
      }
    },
    {
      "key": "trusted_ca_lists",
      "meta": {
        "href": "/api/configuration/policies/trusted_ca_lists"
      }
    },
    {
      "key": "user_databases",
      "meta": {
        "href": "/api/configuration/policies/user_databases"
      }
    },
    {
      "key": "userlists",
      "meta": {
        "href": "/api/configuration/policies/userlists"
      }
    },
    {
      "key": "usermapping_policies",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/policies",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/private_keys",
    "parent": "/api/configuration",
    "previous": "/api/configuration/plugins",
    "transaction": "/api/transaction"
  }
}
Endpoint Description
audit_policies Audit trail encryption, timestamping, and signing.
content_policies Actions for detected commands, screen content, credit card information, and window titles.
credentialstores Local and external credential stores.
indexing Languages for Optical Character Recognition (OCR).
ldap_servers LDAP servers.
signing_cas

Signing CAs for generating the server-side certificates on the fly. You can use such CAs in SSL-encrypted RDP sessions, RDP sessions that use Network Level Authentication (CredSSP), or SSH connections that use X.509-based authentication.

To configure signing for audit trails, use the audit_policies endpoint.

ticketing_policies Integration settings for external ticketing systems.
time_policies Time policies.
trusted_ca_lists Trusted Certificate Authorities (CAs), and options for restricting the accepted certificates.
user_databases Local User Databases are available for RDP, SSH and Telnet protocols, and can be used to authenticate the clients to credentials (passwords, public keys, and certificates) that are locally available on SCB.
userlists Local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.
usermapping_policies Usermapping policies describe who can use a specific username to access the remote server.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.3. Audit policies

The list of audit policies. An audit policy contains settings for encrypting, timestamping, and signing audit trails. To enable auditing for a connection, select an audit policy when configuring connections, and enable auditing for the appropriate protocol channels in the connection's channel policy.

Note

The default audit policy is pre-selected when creating connection policies. Modify that audit policy with care.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/audit_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the audit policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/audit_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/policies/audit_policies/<policy-id>

Response

The following is a sample response received when listing audit policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "78101850949e47437dd91d",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
      }
    },
    {
      "key": "9161063345713f11489305",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/9161063345713f11489305"
      }
    },
    {
      "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/audit_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/content_policies",
    "parent": "/api/configuration/policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific audit policy, the response is the following.

{
  "body": {
    "encryption": {
      "certificates": [
        {
          "certificate": "<cert1>",
          "four_eyes_certificate": "<cert2>"
        }
      ],
      "different_certificates_for_upstream": {
        "certificates": [
          {
            "certificate": "<cert3>",
            "four_eyes_certificate": "<cert4>"
          }
        ],
        "enabled": true
      },
      "enabled": true
    },
    "name": "<policy-name>",
    "signing": {
      "enabled": true,
      "x509_identity": {
        "key": "ec0b6604-37f6-4df6-bd2f-d7879a75b324",
        "meta": {
          "href": "/api/configuration/x509/ec0b6604-37f6-4df6-bd2f-d7879a75b324"
        }
      }
    },
    "timestamping_enabled": true
  },
  "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
  "meta": {
    "first": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
    "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "last": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "next": null,
    "parent": "/api/configuration/policies/audit_policies",
    "previous": "/api/configuration/policies/audit_policies/9161063345713f11489305",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element (string) The configuration elements of the policy.
  encryption   Top level element Audit trail encryption settings.
  name   string The name of the policy. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  signing   Top level element Audit trail signing settings.
    enabled boolean

Set to true to enable audit trail signing.

If signing is enabled, the x509_identity element is also required.

    x509_identity string

Required for signing audit trails.

References the identifier of the X.509 certificate stored on SCB. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  timestamping   boolean Set to true to timestamp the audit trail.
Elements of encryption Type Description
certificates     Top level list Contains the encrypting certificates.
  certificate   string The encrypting certificate. You can replay an encrypted audit trail with the private key of the encrypting certificate.
  four_eyes_certificate   string Additional certificate for joint (4-eyes) encryption. You can only replay a jointly encrypted audit trail with the private keys of both certificates.
different_certificates_for_upstream     Top level item Configures encrypting upstream traffic separately.
  certificates   Top level list The certificates for encrypting upstream traffic.
    certificate string The encrypting certificate. You can replay an encrypted upstream with the private key of the encrypting certificate.
    four_eyes_certificate string Additional certificate for joint (4-eyes) encryption. You can only replay a jointly encrypted upstream with the private keys of both certificates.
  enabled   boolean

Set to true to encrypt the upstream traffic with separate certificate(s).

If upstream encryption is enabled, the certificates element is required.

enabled     boolean

Set to true to enable encrypting audit trails.

If encryption is enabled, the certificates and different_certificates_for_upstream elements are required.

Examples: 

Disable encryption, signing, and timestamping.

{
  "encryption": {
    "enabled": false
  },
  "name": "default",
  "signing": {
    "enabled": false
  },
  "timestamping_enabled": false
}

Encrypt upstream traffic only (single certificate).

{
  "encryption": {
    "certificates": [],
    "different_certificates_for_upstream": {
      "certificates": [
        {
          "certificate": "<cert>",
          "four_eyes_certificate": null
        }
      ],
      "enabled": true
    },
    "enabled": true
  },
  "name": "Upstream_only",
  "signing": {
    "enabled": false
  },
  "timestamping_enabled": false
}

Enable signing and timestamping, no traffic encryption.

{
  "encryption": {
    "enabled": false
  },
  "name": "Sign_and_timestamp",
  "signing": {
    "enabled": true,
    "x509_identity": {
      "key": "9508db81-4a3f-45a7-a2b1-a86f71c56416",
      "meta": {
        "href": "/api/configuration/x509/9508db81-4a3f-45a7-a2b1-a86f71c56416"
      }
    }
  },
  "timestamping_enabled": true
}

Enable signing and timestamping, and encrypt traffic with a single certificate (no separate upstream encryption).

{
  "encryption": {
    "certificates": [
      {
        "certificate": "<cert>",
        "four_eyes_certificate": null
      }
    ],
    "different_certificates_for_upstream": {
      "enabled": false
    },
    "enabled": true
  },
  "name": "API_audit_pol",
  "signing": {
    "enabled": true,
    "x509_identity": {
      "key": "d0286f64-41aa-45e1-ab19-830ac2f99f57",
      "meta": {
        "href": "/api/configuration/x509/d0286f64-41aa-45e1-ab19-830ac2f99f57"
      }
    }
  },
  "timestamping_enabled": true
}

Encrypting certificates

Encrypting certificates must not contain any metadata. SCB uses only the key part of the certificate, no other data (expiry, etc.) are relevant for encryption.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add an audit policy

To add an audit policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new audit policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/audit_policies endpoint. You can find a detailed description of the available parameters listed in Audit policies.

    If the POST request is successful, the response includes the key of the new audit policy. For example:

    {
      "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
        "parent": "/api/configuration/policies/audit_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify an audit policy

To modify an audit policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the audit policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/audit_policies/<policy-key> endpoint. You can find a detailed description of the available parameters listed in Audit policies.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.4. Real-time content monitoring with Content Policies

You can monitor the traffic of certain connections in real time, and execute various actions if a certain pattern (for example, a particular command or text) appears in the command line or on the screen, or if a window with a particular title appears in a graphical protocol. Since content-monitoring is performed real-time, SCB can prevent harmful commands from being executed on your servers. SCB can also detect numbers that might be credit card numbers. The patterns to find can be defined as regular expressions. In case of ICA, RDP, and VNC connections, SCB can detect window title content.

The following actions can be performed:

  • Log the event in the system logs.

  • Immediately terminate the connection.

  • Send an e-mail or SNMP alerts about the event.

  • Store the event in the connection database of SCB.

SCB currently supports content monitoring in SSH session-shell connections, Telnet connections, RDP and Citrix ICA Drawing channels, and in VNC connections.

Note

Command, credit card and window detection algorithms use heuristics. In certain (rare) situations, they might not match the configured content. In such cases, contact the Balabit Support Team to help analyze the problem.

Real-time content monitoring in graphical protocols is not supported for Arabic and CJK languages.

To list the available Content policies, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/content_policies

The following sections detail the properties of Content policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/policies/content_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific Content policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/policies/content_policies/<object-id>

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "name": "example-content-policy-window-title",
    "rules": [
      {
        "actions": {
          "log": true,
          "notify": true,
          "store_in_connection_database": true,
          "terminate": false
        },
        "event": {
          "ignore": [],
          "match": [
            "mmc.exe"
          ],
          "selection": "window_title"
        },
        "gateway_groups": [],
        "remote_groups": []
      }
    ]
  }
}
Element Type Description
name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
rules   JSON object Top level element, contains the configuration properties of the object.
  actions JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  event JSON object Specifies the event that triggers an action.
  gateway_groups list

To apply the Content policy only for users belonging to specific groups, list those groups in the gateway_groups or remote_groups fields. If the gateway_groups or remote_groups field is set, the content policy is applied only to connections of these usergroups.

For example:

"gateway_groups": ["group1", "group2"],
  remote_groups list

To apply the Content policy only for users belonging to specific groups, list those groups in the gateway_groups or remote_groups fields. If the gateway_groups or remote_groups field is set, the content policy is applied only to connections of these usergroups.

For example:

"remote_groups": ["group1", "group3"],
Element Type Description
actions   JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  log boolean

Log the event in the system logs. Possible values: true or false

  terminate boolean

Immediately terminate the connection. Possible values: true or false

  notify boolean

Send an e-mail or SNMP alerts about the event. Possible values: true or false

  store_in_connection_database boolean

Store the event in the connection database of SCB. Possible values: true or false

Element Type Description
event   JSON object Specifies the event that triggers an action.
  ignore list

A list of strings or regular expressions. SCB will perform an action if the match expression is found in the connection, unless it is listed in the ignore list. For example:

"ignore": [
"mmc.exe",
"cmd.exe"
],
  • Use Perl Compatible Regular Expressions (PCRE).

  • The following characters must be escaped using a backslash character: '(single-quote). For example, instead of .*' use .*\'

  • SCB uses substring search to find the expression in the content. That is, SCB finds the expression even if there is more content before or after the matching part. For example, the conf pattern will match the following texts: conf, configure, reconfigure, arcconf, and so on.

  • Using complicated regular expressions or using many regular expressions will affect the performance of SCB.

  • If the multiple expressions are set, SCB processes them one after the other, and stops processing the content if the first match is found, even if other expressions would also match the content. Therefore, when using multiple expressions, start with the most specific one, and add general expressions afterward.

  match list

A list of strings or regular expressions. SCB will perform an action if the match expression is found in the connection, unless it is listed in the ignore list. For example:

"match": [
"mmc.exe",
"cmd.exe"
],
  • Use Perl Compatible Regular Expressions (PCRE).

  • The following characters must be escaped using a backslash character: '(single-quote). For example, instead of .*' use .*\'

  • SCB uses substring search to find the expression in the content. That is, SCB finds the expression even if there is more content before or after the matching part. For example, the conf pattern will match the following texts: conf, configure, reconfigure, arcconf, and so on.

  • Using complicated regular expressions or using many regular expressions will affect the performance of SCB.

  • If the multiple expressions are set, SCB processes them one after the other, and stops processing the content if the first match is found, even if other expressions would also match the content. Therefore, when using multiple expressions, start with the most specific one, and add general expressions afterward.

  selection string

The type of event that you want to monitor.

  • command: The commands executed in the session-shell channel of SSH connections, or in Telnet connections.

    Warning

    During indexing, if a separate certificate is used to encrypt the upstream traffic, command detection works only if the upstream key is accessible on the machine running the indexer.

  • screen_content: Every text that appears on the screen. For example, every text that is displayed in the terminal of SSH or Telnet connections. This includes the executed commands as well, unless echoing is turned off for the terminal.

  • creditcard: Process every text that appears on the screen and attempt to detect credit card numbers in SSH or Telnet connections. SCB performs an action if the number of detected credit card numbers exceeds the value set as Permitted number of credit card numbers.

    Credit card number detection is based on the Luhn algorithm and lists of known credit card number prefixes.

  • window_title: Text appearing as window titles in case of RDP, Citrix ICA, and VNC connections. Only Windows Classic Themes are supported. Themes with rounded corners, or Windows Aero themes are not supported.

For example:

"selection": "window_title"

Add a content policy

To add a content policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new content policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/content_policies endpoint. You can find a detailed description of the available parameters listed in Parameters of Content policies.

    If the POST request is successful, the response includes the key of the new policy. For example:

    {
      "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
      "meta": {
        "href": "/api/configuration/policies/content_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
        "parent": "/api/configuration/policies/content_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a content policy

To modify a content policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the content policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/content_policies/<policy-key> endpoint. You can find a detailed description of the available parameters listed in Parameters of Content policies.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.5. LDAP servers

SCB can authenticate the users of the controlled SSH or RDP connections to LDAP databases.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available LDAP server configurations.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers

The following command retrieves the properties of a specific LDAP server.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers/<object-id>

Response

The following is a sample response received when listing LDAP servers. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "3548834825727acc530407",
      "meta": {
        "href": "/api/configuration/policies/ldap_servers/3548834825727acc530407"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/ldap_servers",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/signing_cas",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/indexing",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific LDAP server, the response is the following.

{
  "body": {
    "base_dn": "basedn",
    "bind_dn": "binddn",
    "bind_password": {
      "key": "f09f94f5-a2c9-4cc5-96ab-2ef1855d12d1",
      "meta": {
        "href": "/api/configuration/passwords/f09f94f5-a2c9-4cc5-96ab-2ef1855d12d1"
      }
    },
    "encryption": {
      "selection": "disabled"
    },
    "generated_publickey_attribute": null,
    "generated_x509_attribute": null,
    "name": "API_LDAP",
    "nested_groups": true,
    "publickey_attribute": "sshPublicKey",
    "schema": {
      "selection": "ad"
    },
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "10.20.30.40"
        },
        "port": 389
      }
    ],
    "x509_attribute": "userCertificate"
  },
  "key": "3548834825727acc530407",
  "meta": {
    "first": "/api/configuration/policies/ldap_servers/3548834825727acc530407",
    "href": "/api/configuration/policies/ldap_servers/3548834825727acc530407",
    "last": "/api/configuration/policies/ldap_servers/17610964665734c0598c669",
    "next": "/api/configuration/policies/ldap_servers/17610964665734c0598c669",
    "parent": "/api/configuration/policies/ldap_servers",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the LDAP server configuration.
body     Top level element (string) Contains the properties of the LDAP server.
  base_dn   string Name of the DN to be used as the base of the queries.
  bind_dn   string Name of the DN where SCB should bind to before accessing the database.
  bind_password   string

References the password SCB uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

  encryption   Top level item Configuration settings for encrypting the communication between SCB and the LDAP server.
  generated_publickey_attribute   string

Set this element to null if you use passwords to authenticate.

Configure this element if you want SCB to generate server-side encryption keys on-the-fly, and store them in a separate attribute on the LDAP server.

  generated_x509_attribute   string

Set this element to null if you use passwords to authenticate.

Configure this element if you want SCB to generate server-side certificates on-the-fly, and store them in a separate attribute on the LDAP server.

  name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  nested_groups   boolean

Set to true to use nested groups when querying the LDAP server.

Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large.

  publickey_attribute   string

Set this element to null if you use passwords to authenticate.

The name of the LDAP attribute that stores the public keys of the users.

  schema   Top level item Contains the configuration settings for the AD schema.
    member_uid_attribute string

Must be used if the selection element is set to posix.

Attribute name of the POSIX group membership.

    selection string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

  • ad

    Microsoft Active Directory server.

  • posix

    Server uses the POSIX LDAP scheme.

    Must be used with the member_uid_attribute, unique_member_attribute and username_attribute elements.

    unique_member_attribute string

Must be used if the selection element is set to posix.

Attribute name of the GroupOfUniqueMemberships membership.

    username_attribute string

Must be used if the selection element is set to posix.

Attribute name of the username (user ID).

  servers   Top level list Contains the addresses and ports of the LDAP servers.
  x509_attribute   string

Set this element to null if you use passwords to authenticate.

The name of the LDAP attribute that stores the certificates of the users.

Elements of encryption Type Description
client_authentication   Top level item

Must be used with the selection child element.

Configures the X.509 certificate SCB uses to authenticate on the LDAP server.

  enabled boolean

Must be used with the client-authentication parent element.

Set to true if the LDAP server requires mutual authentication.

  x509_identity string

Must be used if the enabled element is set to true.

References the identifier of the X.509 certificate stored on SCB. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

selection   string

Defines the type of encryption SCB uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

server_certificate_check   Top level item

Must be used with the selection child element.

Configuration settings for verifying the LDAP server's certificate.

  enabled boolean

Must be used with the server_certificate_check parent element.

Set to true to verify the LDAP server's certificate using the certificate of a Certificate Authority (CA).

  server_certificate_ca string

Must be used if the enabled element is set to true.

The certificate of the CA.

Elements of servers Type Description
host   Top level item Contains the address of the LDAP server.
  selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

  value string The address of the LDAP server.
port   int The port of the LDAP server.

Examples: 

Configure a POSIX server without communication encryption.

{
  "base_dn": "<basedn>",
  "bind_dn": "<binddn>",
  "bind_password": "<bind-password>",
  "encryption": {
    "client_authentication": {
      "enabled": false
    },
    "selection": "ssl",
    "server_certificate_check": {
      "enabled": false
    }
  },
  "generated_publickey_attribute": null,
  "generated_x509_attribute": null,
  "name": "<name-of-ldap-policy>",
  "nested_groups": true,
  "publickey_attribute": "<sshPublicKey>",
  "schema": {
    "member_uid_attribute": "<memberUid>",
    "selection": "posix",
    "unique_member_attribute": "<uniqueMember>",
    "username_attribute": "<uid>"
  },
  "servers": [
    {
      "host": {
        "selection": "fqdn",
        "value": "<server-name>"
      },
      "port": <server-port>
    }
  ],
  "x509_attribute": "<userCertificate>"
}

Configure a Microsoft Active Directory server with mutual authentication, and the verification of the server's X.509 certificate.

{
  "base_dn": "<basedn>",
  "bind_dn": "<binddn>",
  "bind_password": "<key-of-password>",
  "encryption": {
    "client_authentication": {
      "enabled": true,
      "x509_identity": "<key-of-cert>"
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": true,
      "server_certificate_ca": "<ca-cert>"
    }
  },
  "generated_publickey_attribute": null,
  "generated_x509_attribute": null,
  "name": "<name-of-ldap-policy>",
  "nested_groups": true,
  "publickey_attribute": "<sshPublicKey>",
  "schema": {
    "selection": "ad"
  },
  "servers": [
    {
      "host": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "port": <server-port>
    }
  ],
  "x509_attribute": "<userCertificate>"
}

CA certificates

CA certificates must not contain any metadata. SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add an LDAP server

To add an LDAP server, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new LDAP server. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers endpoint. You can find a detailed description of the available parameters listed in LDAP servers.

    If the POST request is successful, the response includes the key of the new LDAP server. For example:

    {
      "key": "f9f9783c-1e28-4ce8-a650-fc4c7311ac52",
      "meta": {
        "href": "/api/configuration/policies/ldap_servers/f9f9783c-1e28-4ce8-a650-fc4c7311ac52",
        "parent": "/api/configuration/policies/ldap_servers",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify an LDAP server

To modify the configuration of an LDAP server, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the LDAP server. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in LDAP servers.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.6. Signing CA policies

SCB can generate the server-side certificates on the fly. This technique is used for example in SSL-encrypted RDP sessions, RDP sessions that use Network Level Authentication (CredSSP), or SSH connections that use X.509-based authentication.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/signing_cas

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configured signing Certificate Authorities (CAs).

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/signing_cas

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/signing_cas/<object-id>

Response

The following is a sample response received when listing signing CAs. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "991699365727ac4eb4606",
      "meta": {
        "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/signing_cas",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/ticketing_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/ldap_servers",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific signing CA, the response is the following.

{
  "body": {
    "ca": {
      "key": "55b2419c-f94f-4836-9c0b-bc3796b6f556",
      "meta": {
        "href": "/api/configuration/x509/55b2419c-f94f-4836-9c0b-bc3796b6f556"
      }
    },
    "name": "API_CA"
  },
  "key": "991699365727ac4eb4606",
  "meta": {
    "first": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "last": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "next": null,
    "parent": "/api/configuration/policies/signing_cas",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the signing CA.
body   Top level element (string) Contains the properties of the signing CA.
  ca string

References the identifier of the signing CA's X.509 certificate. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  name string The name of the signing CA. This name is also displayed on the SCB web interface. It cannot contain whitespace.

Add a signing CA

To add a signing CA, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create a signing CA. Have the value of the key element of a valid X.509 CA certificate stored on SCB.

  3. Create the JSON object for the new signing CA. Use the X.509 certificate's key as the value of the ca element for the signing CA. You can find a detailed description of the available parameters listed in Signing CAs.

    POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/signing_cas endpoint. If the POST request is successful, the response includes the key of the new signing CA. For example:

    {
      "key": "325768b5-5b85-467d-8e30-e2b57d0869c8",
      "meta": {
        "href": "/api/configuration/policies/signing_cas/325768b5-5b85-467d-8e30-e2b57d0869c8",
        "parent": "/api/configuration/policies/signing_cas",
        "transaction": "/api/transaction"
      }
    }
  4. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a signing CA

To modify a signing CA, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the signing CA. Use the X.509 certificate's key as the value of the ca element for the signing CA. You can find a detailed description of the available parameters listed in Signing CAs.

    PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/signing_cas/<key-of-the-object> endpoint.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
400

Bad Request

"message": "Signing certificate is not CA;

The referenced certificate is not a valid CA certificate.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.7. Time policy

The time policy determines the timeframe when the users are permitted to access a particular channel. To list the available Time policies, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/time_policies

The following sections detail the properties of Time policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/policies/time_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific Time policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/policies/time_policies/<object-id>

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "Fri": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Mon": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sat": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sun": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Thu": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Tue": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Wed": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "name": "7x24"
}
Element Type Description
name string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
Fri list

A list of intervals for the day when the users are allowed to access the connection. Use the hh:mm format.

If the users are not allowed to access the connection for this day, use an empty list. For example:

"Sat": [],

To allow access for the whole day, use 0:00 for the starting time, and 23:59for the end. For example:

"Wed": [
  [
    "0:00",
    "23:59"
  ]
]

You can list multiple intervals for a day, for example:

"Wed": [
  [
	"8:00",
	"18:00"
  ],
  [
	"19:00",
	"22:00"
  ]
]
Sat list
Sun list
Thu list
Tue list
Wed list

6.8. Trusted Certificate Authorities

SCB can check the validity of certificates using the certificates and certificate-revocation lists of trusted certificate authorities (CAs) that issued the certificates.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the trusted CAs.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists

The following command retrieves the properties of a specific CA.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists/<policy-id>

Response

The following is a sample response received when listing trusted CAs. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "12269547065727ad6e79d9e",
      "meta": {
        "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/trusted_ca_lists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/user_databases",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/time_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific CA, the response is the following.

{
  "body": {
    "authorities": [
      {
        "certificate": "<cert>",
        "crl": "<url-of-revocation-list>"
      }
    ],
    "dn_check": {
      "altEmailAddress": "<altEmail>",
      "c": "<country>",
      "cn": "<commonName>",
      "emailAddress": "<email>",
      "l": "<localityName>",
      "o": "<orgName>",
      "ou": "<orgUnitName>",
      "st": "<stateOrProvince>"
    },
    "dns_lookup": false,
    "name": "<ca-name>",
    "strict_hostcheck": true
  },
  "key": "12269547065727ad6e79d9e",
  "meta": {
    "first": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "last": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "next": null,
    "parent": "/api/configuration/policies/trusted_ca_lists",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the CA.
body     Top level element (string) Contains the properties of the CA.
  authorities   Top level list

Contains the certificates and the Certificate Revocation Lists (CLR) of the trusted CAs.

You can add multiple certificate and CRL pairs.

    certificate string The certificate of the trusted CA.
    crl string The URL of the Certificate Revocation List of the CA.
  dn_check   Top level item Certificates are only accepted if their content matches the configured values.
    altEmailAddress string The certificate is only accepted if its alternative e-mail address matches the value of the altEmailAddress element.
    c string The certificate is only accepted if its country matches the value of the c element.
    cn string The certificate is only accepted if its common name matches the value of the cn element.
    emailAddress string The certificate is only accepted if its e-mail address matches the value of the emailAddress element.
    l string The certificate is only accepted if its locality matches the value of the l element.
    o string The certificate is only accepted if its organization name matches value of the o element.
    ou string The certificate is only accepted if its organization unit name matches value of the ou element.
    st string The certificate is only accepted if its state or province matches value of the st element.
  dns_lookup   boolean Set to true to use the domain name server set on the /api/configuration/network/naming endpoint to resolve the hostnames and IP addresses for certificate validation. If you have enabled strict_hostcheck, you probably want to enable this option as well.
  name   string The name of the trusted CA. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  strict_hostcheck   boolean Set to true to configure only accepting certificates where the Common Name of the certificate contains the hostname or the IP address of the host showing the certificate.

Uploading CA certificates

SCB uses only the key part of the CA certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add a trusted CA

To add a trusted CA, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new trusted CA. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists endpoint. You can find a detailed description of the available parameters listed in Trusted CAs.

    If the POST request is successful, the response includes the key of the new trusted CA. For example:

    {
      "key": "becc17b1-e876-4443-b22e-a3baf7825e55",
      "meta": {
        "href": "/api/configuration/policies/trusted_ca_lists/becc17b1-e876-4443-b22e-a3baf7825e55",
        "parent": "/api/configuration/policies/trusted_ca_lists",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a trusted CA

To modify a trusted CA, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the trusted CA. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Trusted CAs.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.9. Local user databases

Local User Databases are available for RDP, SSH and Telnet protocols, and can be used to authenticate the clients to credentials that are locally available on SCB. Such credentials include passwords, public keys, and certificates. Local User Databases are most commonly used in inband gateway authentication scenarios.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/user_databases

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists local user databases.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/user_databases

The following command retrieves the properties of a specific local user database.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/user_databases/<object-id>

Response

The following is a sample response received when listing local user databases. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "8235074425707e306abf39",
      "meta": {
        "href": "/api/configuration/policies/user_databases/8235074425707e306abf39"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/user_databases",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/userlists",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/trusted_ca_lists",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific local user database, the response is the following.

{
  "body": {
    "name": "<name-of-the-user-database>",
    "users": [
      {
        "certificates": [
          "<cert>"
        ],
        "passwords": [
          {
            "key": "ad55822d-fa28-45aa-bca4-220074f770e1",
            "meta": {
              "href": "/api/configuration/passwords/ad55822d-fa28-45aa-bca4-220074f770e1"
            }
          }
        ],
        "public_keys": [
          {
            "selection": "rsa",
            "value": "<public-key>"
          }
        ],
        "username": "<username>"
      }
    ]
  },
  "key": "8235074425707e306abf39",
  "meta": {
    "first": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "href": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "last": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "next": null,
    "parent": "/api/configuration/policies/user_databases",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the local user database.
body     Top level element (string) Contains the properties of the local user database.
  name   string The name of the local user database. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  users   Top level list Contains the password, key, and certificates of each configured user.
    certificates Top level list, string Contains the certificates of the user.
    passwords Top level item

References the password of the user. You can configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

    public_keys Top level list Contains the pubic keys of the user.
    username Top level list, string Name of the user.
Elements of public_keys Type Description
selection string

Possible values are:

  • rsa

    The value element contains an RSA key.

  • dsa

    The value element contains a DSA key.

value string The public key.

Examples: 

Configure password authentication only for test_user. (New passwords can only be provided using the web interface of SCB.)

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [],
      "passwords": [
        "ad55822d-fa28-45aa-bca4-220074f770e1"
      ],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Configure two possible X.509 certificates for test_user, and no other authentication options.

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [
        "<cert1>",
        "<cert2>"
      ],
      "passwords": [],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Uploading certificates

SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add a local user database

To add a local user database, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new local user database. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/user_databases endpoint. You can find a detailed description of the available parameters listed in Local user databases.

    If the POST request is successful, the response includes the key of the new local user database. For example:

    {
      "key": "c4e60325-971a-44bc-ac01-e353dc6320d6",
      "meta": {
        "href": "/api/configuration/policies/user_databases/c4e60325-971a-44bc-ac01-e353dc6320d6",
        "parent": "/api/configuration/policies/user_databases",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a local user database

To modify a local usre database, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the local user database. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/user_databases/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Local user databases.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

6.10. User lists

User lists are local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.

Note

User lists on SCB cannot prevent a user from accessing the server from a local terminal.

You can use user lists when configuring gateway_groups or remote_groups in the allowed_for element of channel policies. For more information on configuring channel policies, see Section 6.1, Channel policy.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/userlists

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the user lists created on SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/userlists

The following command retrieves the properties of a specific list.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/userlists/<key-id>

Response

The following is a sample response received when retrieveing the user lists. For details of the meta object, see Section 1.1, Message format.

The keys with negative ID values are the default user lists of SCB.

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/userlists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/usermapping_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "-1",
      "meta": {
        "href": "/api/configuration/policies/userlists/-1"
      }
    },
    {
      "key": "-2",
      "meta": {
        "href": "/api/configuration/policies/userlists/-2"
      }
    },
    {
      "key": "-3",
      "meta": {
        "href": "/api/configuration/policies/userlists/-3"
      }
    },
    {
      "key": "-4",
      "meta": {
        "href": "/api/configuration/policies/userlists/-4"
      }
    },
    {
      "key": "20088200245706af301b1ba",
      "meta": {
        "href": "/api/configuration/policies/userlists/20088200245706af301b1ba"
      }
    }
  ]
}

When retrieving the endpoint of a specific user list, the response is the following.

{
  "body": {
    "default": "exclude",
    "name": "root_only",
    "users": [
      "root"
    ]
  },
  "key": "-4",
  "meta": {
    "first": "/api/configuration/policies/userlists/-1",
    "href": "/api/configuration/policies/userlists/-4",
    "last": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "next": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "parent": "/api/configuration/policies/userlists",
    "previous": "/api/configuration/policies/userlists/-3",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the user list
body   Top level element (string) The elements of the user policy.
  default string

The default policy of the user list. Possible values are:

  • include creates a blacklist, where listed users are denied access.

  • exclude creates a whitelist, where only listed user are allowed access.

  name string

The name of the user list.

  users list

The usernames added to the list.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a user list

To add a user list, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new user list. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/userlists endpoint. You can find a detailed description of the available parameters listed in User list elements.

    If the POST request is successful, the response includes the key of the new user list. For example:

    {
      "key": "321314dc-eca0-4e97-b445-0612fedc0165",
      "meta": {
        "href": "/api/configuration/policies/userlists/321314dc-eca0-4e97-b445-0612fedc0165",
        "parent": "/api/configuration/policies/userlists",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify a user list

To modify a user list, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the user list. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/userlists/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in User list elements.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Chapter 7. HTTP connections

7.1. HTTP connections

List of endpoints for configuring the policies, options and connection rules of HTTP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/http

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for HTTP connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/http/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/http/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/http/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/http",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/ica",
    "parent": "/api/configuration",
    "previous": "/api/configuration/datetime",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global HTTP options that affect all connections.
settings_policies List of protocol-level settings (idle and session timeout). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

7.2. Global HTTP options

List of options that affect all HTTP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/http/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists global HTTP options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/options

Response

The following is a sample response received when listing global HTTP options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/options",
    "last": "/api/configuration/http/settings_policies",
    "next": "/api/configuration/http/settings_policies",
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global HTTP options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable HTTP connections, and specify the logging detail.
    enabled boolean Set to true to enable HTTP connections.
    log_level int Defines the logging detail of HTTP connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for HTTP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of HTTP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for HTTP connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of HTTP connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for HTTP connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global HTTP settings

To modify global HTTP settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the global HTTP settings endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/http/options endpoint. You can find a detailed description of the available parameters listed in Global HTTP options. The elements of the audit item are described in Audit elements.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

7.3. HTTP settings policies

HTTP settings policies define protocol-level settings for idle and session timeout. You can create multiple policies, and choose the appropriate one for each HTTP connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/http/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists HTTP settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/settings_policies/<policy-id>

Response

The following is a sample response received when listing HTTP settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-3040010",
      "meta": {
        "href": "/api/configuration/http/settings_policies/-3040010"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/settings_policies",
    "last": "/api/configuration/http/settings_policies",
    "next": null,
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "name": "default",
    "session_timeout": 900,
    "timeout": 300
  },
  "key": "-3040010",
  "meta": {
    "first": "/api/configuration/http/settings_policies/-3040010",
    "href": "/api/configuration/http/settings_policies/-3040010",
    "last": "/api/configuration/http/settings_policies/-3040010",
    "next": null,
    "parent": "/api/configuration/http/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the HTTP settings policy.
  name string Name of the HTTP settings policy. Cannot contain whitespace.
  session_timeout int Session timeout, in seconds.
  timeout int Idle timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.

Add HTTP settings policies

To add a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/http/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in HTTP Settings Policies.

    If the POST request is successful, the response includes the key of the new policy. For example:

    {
      "key": "3848c708-2e1d-4463-b232-0c8c5875ff55",
      "meta": {
        "href": "/api/configuration/http/settings_policies/3848c708-2e1d-4463-b232-0c8c5875ff55",
        "parent": "/api/configuration/http/settings_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify HTTP settings policies

To modify a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/http/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in HTTP Settings Policies.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Chapter 8. Citrix ICA connections

8.1. ICA connections

List of endpoints for configuring the policies, options and connection rules of ICA connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for ICA connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/ica/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/ica/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/ica/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/ica",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/local_services",
    "parent": "/api/configuration",
    "previous": "/api/configuration/http",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global ICA options that affect all connections.
settings_policies List of protocol-level settings (timeout, reliability). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

8.2. Global ICA options

List of options that affect all ICA connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists global ICA options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/options

Response

The following is a sample response received when listing global ICA options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/options",
    "last": "/api/configuration/ica/settings_policies",
    "next": "/api/configuration/ica/settings_policies",
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global ICA options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable ICA connections, and specify the logging detail.
    enabled boolean Set to true to enable ICA connections.
    log_level int Defines the logging detail of ICA connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for ICA connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of ICA connections, in days. Must exceed the retention time of the archiving policy (or policies) used for ICA connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of ICA connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for ICA connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global ICA settings

To modify global ICA settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the global ICA settings endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/options endpoint. You can find a detailed description of the available parameters listed in Global ICA options. The elements of the audit item are described in Audit elements.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

8.3. ICA settings policies

ICA settings policies define protocol-level settings (timeout, reliability). You can create multiple policies, and choose the appropriate one for each ICA connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists ICA settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/<policy-id>

Response

The following is a sample response received when listing ICA settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-301101020",
      "meta": {
        "href": "/api/configuration/ica/settings_policies/-301101020"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/settings_policies",
    "last": "/api/configuration/ica/settings_policies",
    "next": null,
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "name": "default",
    "preconnect_channel_check": false,
    "reliability": {
      "reconnect_attempts": 30,
      "reconnect_sleep": 2,
      "reconnect_timeout": 600
    },
    "timeout": 600
  },
  "key": "-301101020",
  "meta": {
    "first": "/api/configuration/ica/settings_policies/-301101020",
    "href": "/api/configuration/ica/settings_policies/-301101020",
    "last": "/api/configuration/ica/settings_policies/-301101020",
    "next": null,
    "parent": "/api/configuration/ica/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the ICA settings policy.
  name string Name of the ICA settings policy. Cannot contain whitespace.
  preconnect_channel_check boolean

Before establishing the server-side connection, SCB can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server.

To enable this function, set the parameter to true.

  reliability Top level item Settings for ICA connection attempts.
  timeout int Connection timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.
Elements of reliability Type Description
reconnect_attempts int The number of times SCB attempts to connect to the target server.
reconnect_sleep int The number of seconds SCB waits between connection attempts.
reconnect_timeout int The number of seconds SCB waits after exhausting the number of reconnect_attempts.

Add ICA settings policies

To add a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in ICA Settings Policies.

    If the POST request is successful, the response includes the key of the new policy. For example:

    {
      "key": "dcd58077-98b3-4c73-8f0b-b34147863028",
      "meta": {
        "href": "/api/configuration/ica/settings_policies/dcd58077-98b3-4c73-8f0b-b34147863028",
        "parent": "/api/configuration/ica/settings_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify ICA settings policies

To modify a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in ICA Settings Policies.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Chapter 9. RDP connections

9.1. RDP connections

List of endpoints for configuring the policies, options and connection rules of RDP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for RDP connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/rdp/channel_policies"
      }
    },
    {
      "key": "domain_membership",
      "meta": {
        "href": "/api/configuration/rdp/domain_membership"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/rdp/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/rdp",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/reporting",
    "parent": "/api/configuration",
    "previous": "/api/configuration/private_keys",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
domain_membership Domain membership configuration. Prerequisite for configuring Credential Security Service Provider / Network Layer Authentication.
options List of global RDP options that affect all connections.
settings_policies List of protocol-level settings (timeout, display, protocol version, and authentication). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

9.2. RDP channels

The available RDP channel types and their functionalities are described below.

Channel Special options Description
#drawing Yes

Drawing: Enables access to the server's graphical desktop (screen). This channel must be enabled for RDP to work.

Channel-specific actions:

  • content_policy reference: The ID of the Content policy to apply to the connection.

For example:

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}
cliprdr None Clipboard: Enable access to the server's clipboard: the clipboard of the remote desktop can be pasted into local applications (and vice-versa). Note that SCB can audit the clipboard channel, but cannot search or display its contents.
rdpdr Yes

Redirects: Enables access to every device redirections available in RDP, like file-sharing, printer sharing, device (for example CD-ROM) sharing, and so on. To enable only a specific type of redirection, use the specific channels instead (for example, rdpdr-serial for serial device redirection).

Channel-specific actions:

  • log_transfer_to_db (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (true|false): Send the file operations into the system log

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpsnd None

Sound: Enable access to the sound device of the server.

customs Yes

Custom: Applications can open custom channels to the clients connecting remotely to the server. Enabling the Custom channel allows the clients to access all of these custom channels. To permit only specific channels, list the unique names of the channels into the customs field.

For example, to monitor RemoteApp connections, you need to configure custom channels. For more information, see Procedure 10.11, Configuring RemoteApps in The Balabit Shell Control Box 4 F4 Administrator Guide.

Channel-specific access control rules:

  • customs (list): To permit only specific custom channels, list the unique name of the channels in this field. Leave it empty to permit access to every custom channel available.

seamrdp None Seamless: Enable seamless channels that run a single application on the RDP server, instead of accessing the entire desktop.
drdynvc Yes

Dynamic virtual channel: Enable the server to open channels back to the client dynamically. Enabling this channel allows access to all of such dynamic channels. To restrict which dynamic channels are permitted, list the unique names of the channels into the drdynvcs field.

Channel-specific access control rules:

  • drdynvcs (list): To restrict which dynamic channels are permitted, list the unique names of the channels in this field. Leave it empty to permit access to every dynamic channel available.

rdpdr-serial Yes

Serial redirect: Enables access to serial-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-parallel Yes

Parallel redirect: Enables access to parallel-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-printer Yes

Printer redirect: Enables access to printer-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-disk Yes

Disk redirect: Enables access to shared disk drives. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example:

"devices": [
  "C:"
]

Channel-specific actions:

  • log_transfer_to_db (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (true|false): Send the file operations into the system log

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-scard Yes

SCard redirect:Enables access to shared SCard devices. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example:

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

9.3. Configuring domain membership

Joining a domain is required when using Credential Security Service Provider (CredSSP, also called Network Layer Authentication). The target servers and SCB must be in the same domain, or you must establish trust between the domains that contain the target servers and SCB.

The SCB configuration API allows you to view, disable, or modify the domain membership configuration. To join the configured domain, you have to use the web interface of SCB.

URL

GET https://<IP-address-of-SCB>/api/rdp/domain_membership

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options for domain membership.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/rdp/domain_membership

Response

The following is a sample response received when querying the domain membership configuration. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "domain": "testdomain",
    "enabled": true,
    "realm": "testdomain.api.test"
  },
  "key": "domain_membership",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/domain_membership",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/options",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the domain membership configuration.
  domain string

The name of the domain.

Must be used if enabled is set to true.

  enabled boolean Set to true to configure domain membership.
  realm string

Name of the realm.

Must be used if enabled is set to true.

Examples: 

Configure domain membership for the "test" domain on the "config.api" realm:

{
  "domain": "test",
  "enabled": true,
  "realm": "test.config.api"
}

Disable domain membership.

{
  "enabled": false
}

Modify domain membership settings

To modify domain membership settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the domain membership configuration. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/rdp/domain_embership/ endpoint. You can find a detailed description of the available parameters listed in Domain membership configuration.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

9.4. Global RDP options

List of options that affect all RDP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists global RDP options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/options

Response

The following is a sample response received when listing global RDP options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/options",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/settings_policies",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/domain_membership",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global RDP options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable RDP connections, and specify the logging detail.
    enabled boolean Set to true to enable RDP connections.
    log_level int Defines the logging detail of RDP connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for RDP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of RDP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for RDP connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of RDP connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for RDP connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global RDP settings

To modify global RDP settings, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the global RDP settings endpoint. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/options endpoint. You can find a detailed description of the available parameters listed in Global RDP options. The elements of the audit item are described in Audit elements.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

9.5. RDP settings policies

RDP settings policies define protocol-level settings (timeout, display, protocol version, and authentication). You can create multiple policies, and choose the appropriate one for each RDP connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists RDP settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/<policy-id>

Response

The following is a sample response received when listing RDP settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-301",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/-301"
      }
    },
    {
      "key": "-303",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/-303"
      }
    },
    {
      "key": "13298899495727c51f725cf",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/settings_policies",
    "last": "/api/configuration/rdp/settings_policies",
    "next": null,
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "autologon_domain_suffix": "-AUTO",
    "name": "API_test",
    "permit_unreliable_usernames": true,
    "preconnect_channel_check": true,
    "protocol_features": {
      "nla": {
        "enabled": true,
        "require_domain_membership": false
      },
      "rdp4_auth_enabled": true,
      "rdp4_enabled": true,
      "rdp5_enabled": true
    },
    "screen": {
      "maximum_bpp": 32,
      "maximum_height": 2000,
      "maximum_width": 2000
    },
    "timeout": 600
  },
  "key": "13298899495727c51f725cf",
  "meta": {
    "first": "/api/configuration/rdp/settings_policies/-301",
    "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf",
    "last": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf",
    "next": null,
    "parent": "/api/configuration/rdp/settings_policies",
    "previous": "/api/configuration/rdp/settings_policies/-303",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the RDP settings policy.
  autologon_domain_suffix string Enter the suffix that the client will append to the domain when using autologon in conjunction with Network Level Authentication (CredSSP).
  name string Name of the RDP settings policy. Cannot contain whitespace.
  permit_unreliable_usernames boolean Set to true to automatically terminate RDP connections if SCB cannot reliably extract the username.
  preconnect_channel_check boolean

Before establishing the server-side connection, SCB can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server.

To enable this function, set the parameter to true.

  protocol_features Top level item Settings for RDP protocol versions, and Network Layer Authentication.
  screen Top level item Display size and depth settings.
  timeout int Connection timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.
Elements of protocol Type Description
nla   Top level item Settings for Network Level Authentication.
  enabled boolean

Set to true to enable Network Level Authentication.

If set to true, the require_domain_membership element is required in the JSON.

  require_domain_membership boolean

Set to true to require domain membership.

Must be in the JSON if NLA is enabled.

rdp4_auth_enabled   boolean Set to true to enable RDP4 authentication within the RDP5 protocol. This might be needed for compatibility reasons with certain client applications.
rdp4_enabled   boolean Set to true to enable the version 4 of the Remote Desktop Protocol.
rdp5_enabled   boolean

Set to true to enable the version 5 of the Remote Desktop Protocol.

To also configure SSL-encryption for RDP5, enable the nla element, or configure a Signing CA in your connection policies.

Elements of screen Type Description
maximum_bpp int The maximum allowed color depth of the remote desktop, in bits. The following values are valid: 8, 15, 16, 24.
maximum_height int The maximum allowed height of the remote desktop, in pixels.
maximum_width int The maximum allowed width of the remote desktop, in pixels.

Examples: 

Turn off NLA.

{
  "autologon_domain_suffix": "-AUTO",
  "name": "API_test",
  "permit_unreliable_usernames": true,
  "preconnect_channel_check": true,
  "protocol_features": {
    "nla": {
      "enabled": false
    },
    "rdp4_auth_enabled": true,
    "rdp4_enabled": true,
    "rdp5_enabled": true
  },
  "screen": {
    "maximum_bpp": 24,
    "maximum_height": 2000,
    "maximum_width": 2000
  },
  "timeout": 600
}

Configure NLA.

{
  "autologon_domain_suffix": "-AUTO",
  "name": "API_test",
  "permit_unreliable_usernames": true,
  "preconnect_channel_check": true,
  "protocol_features": {
    "nla": {
      "enabled": true,
      "require_domain_membership": false
    },
    "rdp4_auth_enabled": true,
    "rdp4_enabled": true,
    "rdp5_enabled": true
  },
  "screen": {
    "maximum_bpp": 24,
    "maximum_height": 2000,
    "maximum_width": 2000
  },
  "timeout": 600
 }

Add RDP settings policies

To add a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in RDP Settings Policies.

    If the POST request is successful, the response includes the key of the new policy. For example:

    {
      "key": "9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7",
        "parent": "/api/configuration/rdp/settings_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify RDP settings policies

To modify a settings policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in RDP Settings Policies.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400

Bad Request

"message": "RDP Settings Policy 'API_test': SCB must be a domain member to allow enabling Network Level Authentication."

You have set require_domain_membership to true, but SCB is not the member of a domain.

401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Chapter 10. SSH connections

10.1. SSH connections

List of endpoints for configuring the policies, options and connection rules of SSH connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for SSH connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "authentication_policies",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies"
      }
    },
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/ssh/channel_policies"
      }
    },
    {
      "key": "connections",
      "meta": {
        "href": "/api/configuration/ssh/connections"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/ssh/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/ssh",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/telnet",
    "parent": "/api/configuration",
    "previous": "/api/configuration/reporting",
    "transaction": "/api/transaction"
  }
}
Item Description
authentication_policies List of the default and custom authentication policies.
channel_policies List of the default and custom channel policies.
connections List of connection policies.
options List of global SSH options that affect all connections.
settings_policies List of protocol-level settings (algorithms, greetings and banners, timeout). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

10.2. SSH connection policies

Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/connections/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists SSH connection policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/connections/

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/connections/<connection-key>

Response

The following is a sample response received when listing SSH connection policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "8348340645707e2575e3c6",
      "meta": {
        "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/connections",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/options",
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/channel_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific SSH connection policy, the response is the following.

{
  "body": {
    "access_control": [
      {
        "authorizer": "reporting",
        "permission": "audit_and_authorize",
        "require_different_ip": true,
        "require_different_username": true,
        "subject": {
          "selection": "everybody"
        }
      }
    ],
    "active": true,
    "channel_database_cleanup": {
      "days": 550,
      "enabled": true
    },
    "client_side_hostkey": {
      "plain_hostkey": {
        "dsa_key": null,
        "enabled": true,
        "rsa_key": {
          "key": "e5a58682-6189-4477-9415-67c1c9b20b0d",
          "meta": {
            "href": "/api/configuration/private_keys/e5a58682-6189-4477-9415-67c1c9b20b0d"
          }
        }
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "indexing": {
      "enabled": true,
      "policy": {
        "key": "-50000",
        "meta": {
          "href": "/api/configuration/policies/indexing/-50000"
        }
      },
      "priority": 2
    },
    "log_audit_trail_downloads": true,
    "name": "API_test_SSH",
    "network": {
      "clients": [
        "0.0.0.0/24"
      ],
      "ports": [
        22
      ],
      "targets": [
        "192.168.56.102/24"
      ]
    },
    "policies": {
      "aa_plugin": null,
      "archive_cleanup_policy": {
        "key": "1854671967571b9063c4c82",
        "meta": {
          "href": "/api/configuration/policies/archive_cleanup_policies/1854671967571b9063c4c82"
        }
      },
      "audit_policy": {
        "key": "78101850949e47437dd91d",
        "meta": {
          "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
        }
      },
      "authentication_policy": {
        "key": "1895203635707e3340262f",
        "meta": {
          "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
        }
      },
      "backup_policy": {
        "key": "512524636571b903540804",
        "meta": {
          "href": "/api/configuration/policies/backup_policies/512524636571b903540804"
        }
      },
      "channel_policy": {
        "key": "-10000",
        "meta": {
          "href": "/api/configuration/ssh/channel_policies/-10000"
        }
      },
      "credential_store": {
        "key": "505008562571b936560254",
        "meta": {
          "href": "/api/configuration/policies/credentialstores/505008562571b936560254"
        }
      },
      "ldap_server": {
        "key": "250588254571b931066482",
        "meta": {
          "href": "/api/configuration/policies/ldap_servers/250588254571b931066482"
        }
      },
      "settings": {
        "key": "-300",
        "meta": {
          "href": "/api/configuration/ssh/settings_policies/-300"
        }
      },
      "ticketing_policy": null,
      "usermapping_policy": {
        "key": "9328731525704545f5e3de",
        "meta": {
          "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
        }
      }
    },
    "rate_limit": {
      "enabled": true,
      "value": 200
    },
    "server_address": {
      "selection": "original"
    },
    "server_side_hostkey": {
      "plain_hostkey": {
        "enabled": true,
        "hostkey_check": "accept-first-time"
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "source_address": {
      "selection": "box_address"
    },
    "web_gateway_authentication": {
      "enabled": true,
      "groups": [
        "reporting"
      ],
      "require_same_ip": true
    }
  },
  "key": "8348340645707e2575e3c6",
  "meta": {
    "first": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "last": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "next": null,
    "parent": "/api/configuration/ssh/connections",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the SSH connection policy.
body     Top level element (string) The elements of the SSH connection policy.
  access_control   Top level list Collection of access policies. Access policies define who can authorize and audit a connection.
  active   boolean Set to false to suspend the connection policy. Connection settings are preserved.
  channel_database_cleanup   Top level item Configures cleanup of the connection metadata on the connection policy's level.
    days int

Retention time, in days. Must not exceed the retention time of the archive_cleanup_policy, and the retention time configured in the global settings of the SSH protocol.

The global settings of the SSH protocol are available at the api/configuration/ssh/options endpoint.

    enabled boolean Set to true to enable periodical cleanup of the connection metadata.
  client_side_hostkey   Top level item The host keys and X.509 certificates SCB shows to clients.
  indexing   Top level item Configures indexing for the connection policy.
    enabled boolean Set to true to enable indexing the connections.
    policy string

References the identifier of the indexing policy. You can configure indexing policies at the /api/configuration/policies/indexing/ endpoint.

To modify or add an indexing policy, use the value of the returned key as the value of the policy element, and remove any child elements (including the key).

    priority int

Specifies the indexing priority for the connection. Possible values are:

  • 4

    Very low priority.

  • 3

    Low priority.

  • 2

    Normal (default) priority.

  • 1

    High priority.

  • 0

    Very high priority.

  log_audit_trail_downloads   boolean

Set to true to log audit trail downloads.

  name   string The name of the connection policy.
  network      
    clients list, string List of client ("from") IP addresses.
    ports list, integers List of target ports.
    targets list, string List of target IP addresses.
  policies   Top level item List of policies referenced by the connection policy.
    aa_plugin string

References the identifier of the AA plug-in. You can configure AA plug-ins at the /api/configuration/plugins/aa/ endpoint.

To modify or add an AA plug-in, use the value of the returned key as the value of the aa_plugin element, and remove any child elements (including the key).

    archive_cleanup_policy string

References the identifier of the archive/cleanup policy. You can configure archive and cleanup policies at the /api/configuration/policies/archive_cleanup_policies/ endpoint.

To modify or add an archive/cleanup policy, use the value of the returned key as the value of the archive_cleanup_policy element, and remove any child elements (including the key).

    audit_policy string

Cannot be null.

References the identifier of the audit policy. You can configure audit policies at the /api/configuration/policies/audit_policies/ endpoint.

To modify or add an audit policy, use the value of the returned key as the value of the audit_policy element, and remove any child elements (including the key).

    authentication_policy string

Cannot be null.

References the identifier of the authentication policy. You can configure authentication policies at the /api/configuration/ssh/authentication_policies/ endpoint.

To modify or add an authentication policy, use the value of the returned key as the value of the authentication_policy element, and remove any child elements (including the key).

    backup_policy string

References the identifier of the backup policy. You can configure backup policies at the /api/configuration/policies/backup_policies/ endpoint.

To modify or add a backup policy, use the value of the returned key as the value of the backup_policy element, and remove any child elements (including the key).

    channel_policy string

Cannot be null.

References the identifier of the channel policy. You can configure channel policies at the /api/configuration/ssh/channel_policies/ endpoint.

To modify or add a channel policy, use the value of the returned key as the value of the channel_policy element, and remove any child elements (including the key).

    credential_store string

References the identifier of the credential store. You can configure credential stores at the /api/configuration/policies/credentialstores/ endpoint.

To modify or add a credential store, use the value of the returned key as the value of the credential_store element, and remove any child elements (including the key).

    ldap_server string

References the identifier of the LDAP server. You can configure LDAP servers at the /api/configuration/policies/ldap_servers/ endpoint.

To modify or add an LDAP server, use the value of the returned key as the value of the ldap_server element, and remove any child elements (including the key).

    settings string

Cannot be null.

References the identifier of the SSH settings policy. You can configure SSH settings policies at the /api/configuration/ssh/settings_policies/ endpoint.

To modify or add an SSH settings policy, use the value of the returned key as the value of the settings element, and remove any child elements (including the key).

    ticketing_policy string

References the identifier of the ticketing policy. You can configure ticketing policies at the /api/configuration/policies/ticketing_policies/ endpoint.

To modify or add a ticketing policy, use the value of the returned key as the value of the ticketing_policy element, and remove any child elements (including the key).

  rate_limit   Top level element Connection rate limit.
    enabled boolean Set to true to provide a connection rate limit.
    value int The number of connections (per minute) that are allowed in the connection policy.
  server_address   Top level item Defines the address where the clients connect to.
  server_side_hostkey   Top level element

Settings for verifying the server's identity using plain hostkeys and X.509 host certificates.

At least one of the options (plain_hostkey or X509_hostkey) must be enabled.

  source_address   Top level element Allows you to configure Source Network Address Translation (SNAT) on the server side of SCB. SNAT determines the IP address SCB uses in the server-side connection. The target server will see the connection coming from this address.
    selection string

Configures Source Network Address Translation. Possible values are:

  • box_address

    Default. Uses the network address of the logical interface of SCB.

  • original

    Uses the IP address of the client, as seen by SCB.

  • fix

    Uses a fixed address when connecting to the remote server.

    Must be used with the address element.

    address string

Must be used if the value of the selection element is set to fix.

The IP address to use as the source address in server-side connections.

  web_gateway_authentication   Top level item When gateway authentication is required for a connection, the user must authenticate on SCB as well. This additional authentication can be performed out-of-band on the SCB web interface for every protocol.
    enabled boolean Set to true to enable additional gateway authentication on the SCB web interface.
    groups list, string

By default, any user can perform gateway authentication for the connections. You can restrict authentication to members of specific usergroups. Define the usergroups at the /api/configuration/aaa/local_database/groups/ endpoint, and list the name of each groups here.

    require_same_ip boolean Set to true to only accept web gateway authentication from the same host that initiated the connection.
Elements of access_control Type Description
authorizer   string

The usergroup (local or LDAP) who can authorize or audit the connection.

Local usergroups can be added or modified at the /api/configuration/aaa/local_database/groups/ endpoint.

permission   string

Defines the permissions of the authorizer usergroup. Possible values are:

  • audit

    The usergroup with the audit permission can monitor ongoing connections, and download the audit trails of a closed and indexed connection.

  • authorize

    The usergroup with the authorize permission can authorize connection requests.

  • audit_and_authorize

    The usergroup with the audit_and_authorize permission can authorize connection requests, monitor connections, and download the audit trail of closed and indexed connections.

require_different_ip   boolean Set to true to require the authorizing user and its subject to have different IP addresses.
require_different_username   boolean Set to true to require the authorizing user and its subject to have different usernames.
subject   Top level item Defines the subjects of the access control policy.
  group string

The usergroup (local or LDAP) that is subject to the access control policy.

Local usergroups can be added or modified at the /api/configuration/aaa/local_database/groups/ endpoint.

  selection string

Possible values:

  • everybody

    Every user is subject to the access control policy.

  • only

    Requires the group element.

    Members of the usergroup specified in the group element are subject to the access control policy.

Elements of client_side_hostkey Type Description
plain_hostkey     Top level item Configures the RSA and DSA keys SCB shows to the clients.
  dsa_key   string

References the identifier of the DSA key. You can add DSA keys at the /api/configuration/private_keys/ endpoint.

To modify or add a DSA key, use the value of the returned key as the value of the dsa_key element, and remove any child elements (including the key).

  enabled   boolean

Set to true to allow presenting DSA and RSA keys to clients.

You must enable either plain_hostkey or x509_hostkey (or both).

  rsa_key   string

References the identifier of the RSA key. You can add RSA keys at the /api/configuration/private_keys/ endpoint.

To modify or add an RSA key, use the value of the returned key as the value of the rsa_key element, and remove any child elements (including the key).

x509_hostkey     Top level item Configures the X.509 keys SCB shows to the clients.
  enabled   boolean

Set to true to allow presenting X.509 hostkeys to clients.

You must enable either plain_hostkey or x509_hostkey (or both).

  x509   Top level item Parameters for X.509 hostkeys.
    selection string

Possible values:

  • fix

    Presents the same certificate for every connection.

    Must be used with the x509_identity element.

  • generate

    Generates a X.509 certificate for the connection policy.

    Must be used with the signing_CA element.

    signing_ca string

Must be used when generating the X.509 certificate.

References the signing Certificate Authority (CA). You can configure signing CAs at the /api/configuration/policies/signing_cas/ endpoint.

To modify or add a signing CA, use the value of the returned key as the value of the rsa_key element, and remove any child elements (including the key).

    x509_identity string

Must be used when using the same X.509 host certificate across connection policies.

References the identifier of the X.509 certificate stored on SCB. You can configure certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

Elements of server_address Type Description
selection     string

Configures the address where the clients connect to. Possible values are:

  • original

    Connect to the same address specified by the client.

  • nat

    Perform a network address translation on the target address.

    Must be used with the network element.

  • fix

    Must be used with the address and port elements.

  • inband

    Extract the address of the server from the username.

    Must be used with the domains element.

    Optional elements: exception_domains, dns_server, and dns_suffixes.

network     string

Must be used if selection is set to nat.

The target address in IP/prefix format. Example: "10.20.30.40/24".

address     string

Must be used if selection is set to fix.

The IP address of the target server.

port     int

Must be used if selection is set to fix.

The port of the target server.

domains     Top level list

Must be used if selection is set to inband.

  domain   Top level item Lists the address ranges that are included in the connection policy.
    selection string

Specifies if the target address range is provided as a domain or as an IP range. Possible values are:

  • address

    The value of the target address is an IP range.

  • domain

    The value of the target address is a domain.

    value string

The address range of the target server(s).

Use the selection element to specify if the address is an IP range, or a domain.

  port   int The port of the targer server(s).
exception_domains     Top level list

Can only be used if selection is set to inband.

Lists the address ranges that are excluded from the connection policy.

  domain   Top level item Contains the excluded address range.
    selection string

Specifies if the excluded address(es) are provided as a domain or as an IP range. Possible values are:

  • address

    The value of the excluded address is an IP range.

  • domain

    The value of the excluded address is a domain.

    value string

The excluded address(es).

Use the selection element to specify if the address is an IP range, or a domain.

  port   int The excluded port.
dns_server     string

Can only be used if selection is set to inband.

IP address or the hostname of the domain name server used to resolve the address of the target server.

dns_suffixes     list, string

Can only be used if selection is set to inband.

If the clients do not include the domain name when addressing the server (for example they use username@server instead of username@server.example.com), SCB can automatically add domain information (for example example.com).

You can add multiple domain names. SCB attempts to resolve the target address by appending the domain names in the provided order, and uses the first successfully resolved address to establish the connection.

Elements of server_side_hostkey Type Description
plain_hostkey     Top level element Verifies the identity of the servers based on their hostkeys.
  enabled   boolean

Set to true to enable plain hostkey checking.

If enabled, the hostkey_check element is mandatory.

  hostkey_check   string

Defines the method for checking the host keys of the target server. Possible values are:

  • disabled

    Disables host key verification.

  • accept-first-time

    Records the key shown for the first connection, and accepts only the same key for any subsequent connections.

  • accept-known-keys

    Only accepts hostkeys that are already stored on SCB.

    You can manage hostkeys at the /api/ssh-host-keys endpoint.

x509_hostkey     Top level element Verifies the identity of the servers based on their X.509 certificates.
  enabled   string

Set to true to enable X.509 hostkey verification.

If enabled, the x509_check element is mandatory.

  x509_check   Top level item Contains the configuration settings for verifying X.509 certificates.
    selection string

Configures the validation of X.509 certificates. Possible values are:

  • disabled

    Disables X.509 certificate verification.

  • accept-first-time

    Records the X.509 certificate shown for the first connection, and accepts only the same certificate for any subsequent connections.

  • accept-known-certificates

    Only accepts X.509 certificates that are already stored on SCB.

    You can add X.509 certificates at the /api/ssh-host-keys endpoint.

  • accept-signed-by

    Accepts all X.509 certificates that are signed by a trusted Certificate Authority.

    Must be used with the trusted_ca element.

    trusted_ca string

Must be used if the selection element is set to accept-signed-by.

References the identifier of the trusted CA. You can add or modify the list of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the ticketing_policy element, and remove any child elements (including the key).

Examples: 

Note

For practical purposes, the following examples show only the relevant parts of a connection policy JSON object. To modify or add a connection policy, always submit the full JSON object.

Access control list: configuring the "security" usergroup to only audit connections made by the "root_only" usergroup.

"access_control": [
      {
    "authorizer": "security",
    "permission": "audit",
    "require_different_ip": true,
    "require_different_username": true,
    "subject": {
      "group": "root_only",
      "selection": "only"
    }
  }
]

Client-side hostkey: use plain hostkeys uploaded to SCB, and generate X.509 certificates for the connection.

"client_side_hostkey": {
  "plain_hostkey": {
    "dsa_key": "<id-of-dsa-key>",
    "enabled": true,
    "rsa_key": "<id-of-rsa-key>"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509": {
      "selection": "generate",
      "signing_ca": "<key-of-signing-ca>"
    }
  }
}

Policies: configure only the required policies.

"policies": {
  "aa_plugin": null,
  "archive_cleanup_policy": null,
  "audit_policy": "<key-of-audit-policy>",
  "authentication_policy": "<key-of-auth-policy>",
  "backup_policy": null,
  "channel_policy": "<key-of-channel-policy>",
  "credential_store": null,
  "ldap_server": null,
  "settings": "<key-of-settings-policy>",
  "ticketing_policy": null,
  "usermapping_policy": null
}

Target server: use the address specified by the client.

"server_address": {
  "selection": "original"
}

Target server: use a fix address.

"server_address": {
  "address": "<fix-IP>",
  "port": 22,
  "selection": "fix"
}

Target server: configure inband selection, where the client can specify the target address in the username. The target can be either an IP range, or a domain.

"server_address": {
  "dns_server": "<ip-of-dns-server>",
  "dns_suffixes": null,
  "domains": [
    {
      "domain": {
        "selection": "address",
        "value": "<IP-range>"
      },
      "port": 22
    },
    {
      "domain": {
        "selection": "domain",
        "value": "*.example"
      },
      "port": 22
    }
  ],
  "selection": "inband"
}

Server-side hostkey: accept the hostkey or X.509 certificate presented at the first connection, and require the same hostkey or certificate for any subsequent connections.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": true,
    "hostkey_check": "accept-first-time"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-first-time"
    }
  }
}

Server-side hostkey: only accept X.509 certificates that are verified by a trusted CA.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": false
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-signed-by",
      "trusted_ca": "<id-of-trusted-ca>"
    }
  }
}

Source address: use the same fix IP when connecting to the remote server.

"source_address": {
  "address": "<ip-address>",
  "selection": "fix"
}

Web gateway authentication: require the admin usergroup to perform an additional gateway authentication on the SCB web interface. They must authenticate from the same host which initiated the connection.

"web_gateway_authentication": {
  "enabled": true,
  "groups": [
    "admin"
  ],
  "require_same_ip": true
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 2.7, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add an SSH connection policy

To add an SSH connection policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Create the JSON object for the new SSH connection policy. POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/connections/ endpoint. You can find a detailed description of the available parameters listed in SSH connections.

    If the POST request is successful, the response includes the key of the new SSH connection policy. For example:

    {
      "key": "a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
      "meta": {
        "href": "/api/configuration/ssh/connections/a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
        "parent": "/api/configuration/ssh/connections",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

Modify an SSH connection policy

To modify an SSH connection policy, you have to:

  1. Open a transaction. For details, see Section 2.3, Open a transaction.

  2. Modify the JSON object of the SSH connection policy. PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/connections/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in SSH connections.

  3. Commit your changes. For details, see Section 2.4, Commit a transaction.

10.3. SSH channels

The available SSH channel types and their functionalities are described below.

Channel Special options Description
auth-agent None Agent: Forwards the SSH authentication agent from the client to the server.
x11 Yes

X11 Forward: Forwards the graphical X-server session from the server to the client. List the address of the client in the networks field to permit X11-forwarding only to the specified clients. Specify IP addresses or networks (in IP address/Prefix format). For example:

"networks": [
  {
    "selection": "address",
    "value": "192.168.1.1"
  },
  {
    "selection": "address",
    "value": "192.168.1.2"
  }
]
Note

Certain client applications send the Target address as a hostname, while others as an IP address. If you are using a mix of different client applications, you might have to duplicate the channel rules and create IP-address and hostname versions of the same rule.

Channel-specific access control rules:

  • networks (list): To X11-forwarding only to specific clients, list the IP addresses or networks of the clients in this field. Leave it empty to permit access to every client. For details, see Section Limiting addresses in port forwarding.

local-forwards Yes

Local Forward: Forwards traffic arriving to a local port of the client to a remote host. To enable forwarding only between selected hosts, use the local_forwards field. If the local_forwards field is empty, local forwarding is enabled without restriction, the client may forward any traffic to the remote host.

For example:

"local_forwards": [
  {
    "host_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "host_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
]

Channel-specific access control rules:

  • local_forwards (list): To permit local forwarding only to specific addresses, list the addresses in this field. Leave it empty to enable without restriction. In this case the client may forward any traffic to the remote host.

    Enter the source of the forwarded traffic into the originator_address field, the target of the traffic into the host_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the local host that sends data to the remote host), and not the SSH server or the client. For example, to enable forwarding from the 192.168.20.20 host to the remote host 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the host_address field. For details, see Section Limiting addresses in port forwarding.

remote-forwards Yes

Remote Forward: Forwards traffic arriving a remote port of the server to the client. To enable forwarding only between selected hosts, enter their IP addresses into the remote_forwards field. If the remote_forwards field is empty, remote forwarding is enabled without restriction, the SSH server may forward any traffic to the client.

For example:

"remote_forwards": [
  {
    "connected_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "connected_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
]

Channel-specific access control rules:

  • remote_forwards (list): To permit only specific forwardins, list the permitted addresses in this field. Leave it empty to permit forwarding without restrictions.

    Enter the source of the forwarded traffic into the originator_address, the target of the traffic into the connected_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the remote host that sends data to the client), and not the SSH server. For example, to enable forwarding from the 192.168.20.20 remote host to the client 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the connected_address field. For details, see Section Limiting addresses in port forwarding.

session-exec Yes

Session Exec: Execute a remote command (for example rsync) without opening a session shell. List the permitted command in the execs field. You can use regular expressions to specify the commands. This field can contain only letters (a-z, A-Z), numbers (0-9), and the following special characters ({}()*?\\|[]).

Warning

Restricting the commands available in Session Exec channels does not guarantee that no other commands can be executed. Commands can be renamed, or executed from shell scripts to circumvent such restrictions.

Channel-specific access control rules:

  • execs (list): List the permitted command in the execs field. Regular expressions may be used to specify the commands.

For example:

"execs": [
  "top",
  "ls"
]
session-exec-scp Yes

Session Exec SCP: Transfers files using the Secure Copy (SCP) protocol.

Channel-specific actions:

  • log_transfer_to_db (list): (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (list): (true|false): Send the file operations into the system log

For example:

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}
session-subsystem Yes

Session Subsystem: Use a subsystem. Enter the name of the permitted subsystem into the subsystems field.

Channel-specific access control rules:

  • subsystems (list): List the permitted subsystems in this field.

For example:

"execs": [
  "top",
  "ls"
]
session-exec-sftp Yes

Session SFTP: Transfers files using the Secure File Transfer Protocol (SFTP).

Channel-specific actions:

  • log_transfer_to_db (list): (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (list): (true|false): Send the file operations into the system log

For example:

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}
session-shell Yes

Session Shell: The traditional remote terminal session.

Channel-specific actions:

  • content_policy reference: The ID of the Content policy to apply to the connection.

For example:

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}

Limiting addresses in port forwarding

The connected_address, host_address, network, and originator_address options that you can use in SSH channel policies that allow port-forwarding and X11 forwarding have the following parameters.

Element Type Description
connected_address, host_address, network, or originator_address   list of JSON objects Container objects for limiting access to port-forwarding in SSH channel policies. For details, see Section 10.3, SSH channels.
  selection address or network

Specifies the type of the address. Possible values: address or network

  value IPv4 address or network

The IP address, or the network in IP-address:prefix format. For example, 192.168.1.1 or 192.168.0.0/16

10.4. SSH authentication policies

Lists the configured authentication methods that can be used in a connection. Each connection policy uses an authentication policy to determine how the client can authenticate to the target server. Separate authentication methods can be used on the client and the server-side of the connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 2.1, Authenticate to the SCB REST API.

Sample request

The following command lists SSH authentication policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies<object-id>

Response

The following is a sample response received when listing SSH authentication policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-200",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/-200"
      }
    },
    {
      "key": "1895203635707e3340262f",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/authentication_policies",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/channel_policies",
    "parent": "/api/configuration/ssh",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "mode": {
      "gateway_authentication": {
        "selection": "none"
      },
      "gssapi": false,
      "relayed_methods": {
        "certificate": {
          "selection": "disabled"
        },
        "keyboard_interactive": true,
        "password": true,
        "public_key": {
          "selection": "disabled"
        }
      }
    },
    "name": "base"
  },
  "key": "-200",
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies/-200",
    "href": "/api/configuration/ssh/authentication_policies/-200",
    "last": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "next": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "parent": "/api/configuration/ssh/authentication_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element Contains the elements of the policy.
  mode   Top level element Contains the configuration of the policy.
    gateway_authentication Top level item Client-side gateway authentication settings. The value of selection defines which authentication method is used.
    relayed_methods Top level element Server-side authentication settings.
    gssapi boolean Deprecated setting.
  name   string The name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
Elements of gateway_authentication Type Description
selection     string

Defines the authentication method for client-side gateway authentication. Possible values are:

  • none

    Disables client-side gateway authentication.

  • ldap

    Uses the LDAP server configured in the /api/configuration/policies/ldap_servers endpoint).

    To use this option, you must also configure the certificate, password, and public_key elements.

  • local

    Uses the local user database configured in the /api/configuration/policies/user_databases/ endpoint.

    To use this option, you must also configure the certificate, password, public_key, and user_database elements.

  • radius

    Uses one or more Radius servers for authentication.

    To use this option, you must also configure the servers element.

certificate     Top level item

Configures authentication with an X.509 certificate.

The enabled child element is required for this option. To enable it, you must also configure the trusted_ca child element.

  enabled   boolean

Possible values:

  • true

    Enables client-side, X.509 certification-based authentication. You must also use the trusted_ca element to define a certificate authority.

  • false

    Disables client-side, X.509 certificate-based authentication.

  trusted_ca   string

References the key of the trusted CA. You can configure trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify o