Proxedo API Security: Administration Guide

Copyright © 2019 Balasys IT Ltd.. 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 Balasys.

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 (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

Linux™ is a registered trademark of Linus Torvalds.

Windows™ 10 is registered trademarks of Microsoft Corporation.

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

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

The Proxedo™ name and the Proxedo™ logo are registered trademarks of Balasys IT Ltd.

AMD Ryzen™ and AMD EPYC™ are registered trademarks of Advanced Micro Devices, Inc.

Intel® Core™ and Intel® Xeon™ are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

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

DISCLAIMER

Balasys is not responsible for any third-party websites mentioned in this document. Balasys 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. Balasys 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.

2021-05-12 .Copyright

Preface

Typographical conventions

Before you start using this guide, it is important to understand the terms and typographical conventions used in the documentation. For more information on specialized terms and abbreviations used in the documentation, see the Glossary at the end of this document.

The following text formatting principles and icons identify special information in the document.

Tips provide best practices and recommendations.

Notes provide additional information on a topic, and emphasize important facts and considerations.

Warnings mark situations where loss of data or misconfiguration of the device is possible if the instructions are not obeyed.

Command: Commands you have to execute.
Emphasis: Reference items, additional readings.
/path/to/file: File names.
Parameters: Parameter and attribute names.

In the parameter listing tables the required parameters are also emphasized with bold text:

Key	Description
param1	This is a required parameter.
param2	This is an optional parameter.

Key

Description

param1

This is a required parameter.

param2

This is an optional parameter.

Additional marks used specifically in the Web User Interface (UI):

Key	Description
*	The elements marked with * in the configuration reference tables are mandatory to be configured.
(Default)	For some of the configuration elements there are recommended default values, marked as (Default). In case the value is not defined during the configuration, the default value will be considered for the actual element.
+	By clicking this sign you can add the actual element to the configuration.

Key

Description

The elements marked with * in the configuration reference tables are mandatory to be configured.

(Default)

For some of the configuration elements there are recommended default values, marked as (Default). In case the value is not defined during the configuration, the default value will be considered for the actual element.

By clicking this sign you can add the actual element to the configuration.

Contact and support information

This product is developed and maintained by Balasys IT Ltd..

Contact:

Balasys IT Ltd.
4 Alíz Street
H-1117 Budapest, Hungary
Tel: +36 1 646 4740
E-mail: <info@balasys.hu>
Web: http://balasys.hu/

Sales contact

You can directly contact us with sales-related topics at the e-mail address <sales@balasys.hu>, or leave us your contact information and we call you back.

Support contact

To access the Balasys Support System, sign up for an account at the Balasys Support System page. Online support is available 24 hours a day.

Balasys Support System is available only for registered users with a valid support package.

Support e-mail address: <support@balasys.hu>.

Training

Balasys IT Ltd. holds courses on using its products for new and experienced users. For dates, details, and application forms, visit the https://www.balasys.hu/hu/support/trainings webpage.

1. Scope of this document

This document describes the Web User Interface for the Proxedo API Security. The purpose of this document is to present the designed approach and the usage for the configuration of Proxedo API Security via Web User Interface (UI). The Web UI allows easy configuration for Proxedo API Security. All the functionalities are grouped visually and logically into thematic units which follow the logical built up of Proxedo API Security’s configuration. The primary intended audience of this document are system engineers and system designers for configuring Proxedo API Security systems.

2. Introduction to Proxedo API Security

2.1. What is Proxedo API Security

The Proxedo API Security (PAS) is a security solution that protects API serving endpoints. It is positioned in the network flow between consumers of the APIs (clients) and backend solutions serving the API (servers) as a transparent HTTP proxy.

Proxedo API Security can:

handle incoming Transport Layer Security v1 (TLS) connections from clients & outgoing TLS connections to servers separately and selectively
verify that the communication conforms to HTTP specifications
verify that the content of the messages conform to their specified content type
verify that the content of messages conform to API specification(s) as described in schemas
extract parts of the content of the messages and relay them to external data stores such as log servers, SIEM systems or other data warehouses

2.2. Where to start

Depending on what you need to do the following starting points are suggested:

To understand what the product does and how, see Overview of Proxedo API Security.
- If you are familiar with API terminology jump right to Architecture for Proxedo API Security.
See Installation of Proxedo API Security if you need to set up a new PAS.
The Operations chapter is about how to manage a working system on the level of the operating system.
Configuration of Proxedo API Security on the Web User Interface contains in-depth information about everything that can be configured with the help of the Web User Interface.
If you are already familiar with the system and need to find a component that suits your needs consult the Matcher types and their settings - Table 1, Comparators, Extractor types or Target.

3. Overview of Proxedo API Security

3.1. Main features

3.1.1. TLS

Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.

The TLS framework inspects TLS connections, and also any other connections embedded into the encrypted TLS channel. TLS connections initiated from the client are terminated on the Proxedo API Security, and two separate TLS connections are built: one between the client and the firewall, and one between the firewall and the server. If both connections match the configuration settings of PAS (for example, the certificates are valid, and only the allowed encryption algorithms are used), PAS inspects the protocol embedded into the secure channel as well. Note that the configuration settings can be different for the two connections, for example, it is possible to permit different protocol versions and encryption settings.

3.1.2. Enforcement

Proxedo API Security acts as an HTTP proxy and verifies that the traffic passing through conforms to HTTP’s specifications. By using OpenAPI schemas, as defined in OpenAPI specifications (also known as Swagger), it also verifies that the traffic passing through conforms to the API enpoint’s specification and can log or deny non-conforming traffic.

PAS also provides its own versatile filtering system to control passing traffic.

3.1.3. Insights

With Proxedo API Security it is possible to extract business-relevant information with extremely high resolution from the traffic and relay it to external data stores where further analysis can be implemented.

Thus, it is possible to feed Log Management solutions, Monitoring and SIEM systems, Data visualization tools with data extracted from the traffic, even to the level of specific fields deep inside API calls or URI parameters.

3.1.4. Security flow

The security flow binds most of PAS’s features together. It allows flexible configuration for handling the traffic. Multiple Enforcement, Filter and Insight plugins can be mix-and-matched with control over error policies.

3.2. Main Concepts in Proxedo API Security

This chapter provides an overview of the Proxedo API Security solution, introduces its main concepts, and explains the relationship of the various components.

API Endpoint

Proxedo API Security protects API endpoints. An API endpoint is the serving part of the communication channel and is the collection of all functions of a service. It resides at a list of well-known top URIs under which all the functions are accessible. APIs have well-defined HTTP Endpoints for all exposed calls, resources etc., usually through providing a schema that describes all parameters of these URI paths, including possible HTTP response codes, the format and fields of the data structure in the request’s and response’s body.

Client

It is a consumer of API endpoints. It is the source of the requests.

Backend

The backend constitutes of one or more servers that serve the API endpoint. It receives the requests of the client and sends the responses.

HTTP message

It can be an HTTP request coming from the client or an HTTP response coming from the backend.

Call

An HTTP conversation constitutes of a request — response interchange of HTTP messages between the client and the backend. Whenever the direction is irrelevant in the context — it applies to both requests and responses — the message is named Call.

Listener

It is the part of PAS that listens to incoming traffic for given API Endpoints. It is bound to a network port. Clients address this port when accessing API Endpoints through the gateway.

TLS

Transport Layer Security is the cryptographic protocol that secures HTTPS communications. PAS can apply TLS encryption both when communicating with Clients and Backends.

Security flow

It provides a collection of security rules that PAS applies to a Call. It is two series of Plugins: one for requests and one for responses.

Plugin

It is an element of the security flow that applies a specific security function. It has different types based on the role they do.

Decompressor: It is a Plugin responsible for decompressing compressed content in the HTTP message’s body. This ensures that the original content of the message is available for processing.
Compressor: It is a Plugin responsible for compressing the result of a flow and forwarding the compressed content.
Deserializer: It is a Plugin responsible for parsing the HTTP message’s body to structured data. This ensures that a message is well-formed. The structured data will also be consumed by other Plugins that operate on the body of the message.
Serializer: It is a Plugin responsible for serializing the structured data to the format of the HTTP message’s body.
Filter: It is a Plugin that rejects calls when they match defined rules.
Enforcer: It is a Plugin that validates calls against externally defined schemas.
Insight: It is a Plugin that extracts various data from the call and sends it to external systems (log servers, SIEMs, and other data analysis tools).

Brick

They are reusable components of Plugins. They can be defined on their own and then shared by multiple Plugins.

Error policy: It is a brick that defines what happens if the Plugin has found an error. It decides if calls are rejected or merely logged, and defines the details of the HTTP error response sent to the client if a call is rejected.
Matcher: It is a brick that decides if the Plugin should be executed for a given call by checking various data in the HTTP message.
Selector: Selector is a brick that can extract a piece of information from a call. It is used by Insight plugins.
Target: It is a brick that defines an external system to send extracted data to. It is used by Insight plugins.

3.3. Architecture for Proxedo API Security

Proxedo API Security is based on a micro-services architecture.

The components of the architecture are each responsible for well-defined subset of handling traffic between the client and the backend. Proxedo API Security is built up of three components:

Transport Director

It manages the transport layer of API connections:

handles network connections from the client
handles network connections towards the backends
handles TLS on these connections
load-balances between multiple backend servers
load-balances between multiple Flow Directors
enforces HTTP protocol validity in calls

Flow Director

It is responsible for the execution of the Plugins in the Endpoint’s flow and for applying Error Policies as necessary.

Insight Director

It manages the connections to Targets. It is responsible for sending the data collected by Insight plugins to Target systems.

The handling of a connection with the help of components is shown in this figure:

Figure 1. PAS Architecture

Incoming connections are accepted by the Transport Director.
- It handles TLS with the client if necessary.
It hands over the connection to the Flow Director.
- The Flow Director chooses the Endpoint based on the URL.
- The Flow Director applies the Endpoint specific Request Security Flow.
If an Insight plugin needs to send data to an external Target it sends the collected data to the Insight Director.
The Insight Director sends the data further to the Target with the appropriate protocol.
The Flow Director hands the connection back to the Transport Director.
The Transport Director then sends the data to the Backend.
- It handles TLS with the backends if necessary.
- It performs load balancing among Backend servers if necessary.

The same procedure is executed with the response coming from the Backend.

3.3.1. Understanding processing flow

The figure on Proxedo API Security architecture and the steps following that describe how client connection is handled. The following figure explains how calls are processed in more details:

Figure 2. PAS processing flow

As shown in the figure above, the incoming connection from the client is handled by the Transport Director, applying TLS if needed.
The Transport Director hands over the connection to the Flow Director, indicating which Listener the connection belongs to.
The Flow Director then chooses the Endpoint based on the URL in the request. First endpoint has matching URL is chosen.
The Flow Director then starts applying the request part of the Security Flow definition.
For each Plugin the Flow Director:
- Checks if the Plugin's matcher matches the request.
- If so, it executes the Plugin, if not, it executes the next Plugin.
- If the Plugin indicates success it executes the next Plugin.
- If the Plugin indicates an error it applies the Plugin's error policy. If the policy dictates to abort the connection:
  - It fills error details and hands back the connection to the Transport Director, aborting the execution of the flow.
  - The Transport Director closes the connection, sending error details to the client if allowed by the policy.
Once, the last Plugin has been executed the connection is handed back to the Transport Director.
The Transport Director initiates the connection towards the Backend:
- It handles load balancing if necessary.
- It handles TLS if necessary.
- It sends the request itself to the Backend server.
The Backend server sends its response to the Transport Director.
Once, the response has been received the Transport Director again hands over the connection to the Flow Director.
The Flow Director then starts applying the response part of the Security Flow definition, executing the Plugins as above.
Once, the last Plugin has been executed the connection is handed back to the Transport Director.
Finally, the Transport Director sends the response to the client.

Usually, Plugins are organized in the following manner:

A Decompressor Plugin extracts the compressed body.
A Deserializer Plugin processes the decompressed request to understand the details in the body.
Filters are applied to filter unnecessary traffic.
Enforcers are applied for detailed validation of calls.
Insights are applied to collect data from the call.
Serializer Plugin serializes the body
Compressor Plugin compresses the serialized body

Though the order of the plugins can be changed based on the needs, note the followings:

When a Plugin needs access to the request body it requires Deserialized data. It is therefore strongly recommended that the first plugin is a Decompressor followed by a Deserializer.
At the end of the flow it is strongly recommended to place a Serializer plugin followed by a Compressor.
Generally Insights are applied after Filters and Enforcers so that they are not executed on possibly invalid calls.
Anything that operates on the HTTP headers or the body of the message will be aware of the call direction: The same Plugin in the request and response flow will act on the request or response data.
However, the Flow Director handles a request-response exchange together, so you can still use details from the request in Plugins of the response flow. The most notable example of this is using URI or method matchers in the response flow.
Plugins in the request flow, however, cannot access details of the response flow (since they are not available yet.)

It is also worth noting that Insight Plugins instantly hand over data to the Insight Director, and let the execution continue.

4. Installation of Proxedo API Security

The installation of Proxedo API Security is relatively straightforward. PAS is mainly distributed as Docker images, and is also completed with a .deb package that sets up the operational environment. You need to install both the core and the management components on the same machine.

4.1. Prerequisites

The followings are needed prior to the installation of Proxedo API Security:

the licence for PAS
a technical user for accessing Balasys' download site and docker registry
the PAS core and management .deb packages

You can download the .deb packages from the Balasys Download website.
a server with Ubuntu 18.04 Operating System installed

4.2. Installation steps for the management component

Log in as root.
Update the OS' package list: apt update.
Install the PAS management .deb package: apt install <path/to/deb>/proxedo-api-security-mgmt_<version>.deb.

This will:

Create a user named pas for running and configuring PAS.

pas user must not be created manually beforehand.
Install the necessary configuration files and helper scripts under /opt/balasys.

Create systemd services for managing the PAS management component.

You need to use apt to locally install the .deb package as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.

Change to the PAS user: su - pas.

Set up MINIO_* and CONSUL_* parameters in /opt/balasys/etc/infrastructure/mgmt/docker-compose.conf. You can also modify other parameters if necessary, including port numbers and the version. For details, see docker-compose.conf.

For HOSTNAME parameters, use the fully qualified domain name or the IP address of the machine. For keys and tokens, you should define the values you want to use. Pick strong and preferably random-generated values.

Run pas-mgmt-registry-login to set up authentication with the docker registry. Provide login credentials on the prompt. Contact support if you need assistance with your credentials.

Docker will, by default, save your credentials unencrypted in the home directory of the pas user. Using a password-management tool like pass is not enforced, but it is recommended.
Run pas-mgmt-update to download the docker images.
Set up startup configuration in /opt/balasys/etc/mgmt/config.yml.
Run pas-mgmt-checkconfig to validate the configuration.
Start PAS management: systemctl start proxedo-api-security-mgmt.

This service is enabled by default, so the service starts on system restart.

4.3. Installation steps for the core component

Log in as root.
Update the OS' package list: apt update.
Install the PAS .deb package: apt install <path/to/deb>/proxedo-api-security_<version>.deb.

This will:

create a user named pas for running and configuring PAS.

pas user must not be created manually beforehand.
Install the necessary configuration files and helper scripts under /opt/balasys.

Create systemd services for managing PAS.

Change to the PAS user: su - pas.
Set up MINIO_* and CONSUL_* parameters and the number of Flow Director instances to run in /opt/balasys/etc/infrastructure/pas/docker-compose.conf. If necessary, also change the version you want to follow.

For MinIO- and Consul-related parameters, you must use the same values as you did in /opt/balasys/etc/infrastructure/mgmt/docker-compose.conf. For details, see docker-compose.conf.
Copy license.txt to /opt/balasys/etc/pas.
Run pas-registry-login to set up authentication with the docker registry. Provide login credentials on the prompt. Contact support if you need assistance with your credentials.

Docker will, by default, save your credentials unencrypted in the home directory of the pas user. Using a password-management tool like pass is not enforced, but it is recommended.
Run pas-update to download the docker images.

Start PAS: systemctl start proxedo-api-security.

Starting PAS core will only succeed once you have a functional configuration set up in the management component. To do it, please refer to Configuration of Proxedo API Security on the Web User Interface.

This service is enabled by default, so the service starts on system restart.

If you configured Certificate Revocation List (CRL) verification in any of your Backends or Listeners you need to enable CRL updates:

sytemctl enable proxedo-api-security-crl-update.service
sytemctl enable proxedo-api-security-crl-update.timer
sytemctl start proxedo-api-security-crl-update.timer

5. Base system configuration

This chapter explains configuration details for setting up a working PAS. Configuration settings are detailed here, provided by the .deb packages installed on an Ubuntu 18.04 LTS server.

The .deb packages carry convenience tools for managing the Proxedo API Security core and the management component, the actual installation and execution is done by Docker and docker-compose.

5.1. docker-compose.yml

The main configuration of the running environment is the defined in /opt/balasys/etc/infrastructure/pas/docker-compose.yml and /opt/balasys/etc/infrastructure/mgmt/docker-compose.yml files. They describe the containers running PAS.

The format of the files must adhere to the YAML 1.1 specification. For a brief overview of the YAML format look at the example here. For an in-depth reference of docker-compose configuration see its documentation.

This file controls:

the images to run the container from
the persistent data storage (docker volumes) to attach to the containers
the ports propagated to the containers
the environment variables available inside the containers
intra container communication channels (links)
log target configuration

Unless inevitable, you should not modify these files. There are two cases when you might need to.

If you need to modify the provided environment to debug your setup.
If you need to change the default behavior of logging into the system’s journal you must change the logging parameters under all the services. See more details in docker-compose’s documentation.

If you modify these files, they will not be overwritten on package upgrade. Only interactive installs will notify you.

Do not use docker-compose directly to manage the installation. Always use systemctl as it handles dependencies and scaling.

5.2. docker-compose.conf

Some aspects of how the services are run by docker-compose are configured through /opt/balasys/etc/infrastructure/pas/docker-compose.conf and /opt/balasys/etc/infrastructure/mgmt/docker-compose.conf.

The format of this file is a shell environment file format: a key-value pair in each line, separated by an equal sign ("=").

There must not be spaces around the equal sign.

The configuration files of different components have a common portion along with other parameters that are only valid in one of them. For details, see the following tables.

Table 1. docker-compose.conf configuration common options
Key	Default	Description
PAS_IMAGE_TAG	3.0.latest	The release track of Proxedo API Security to use. See Tracking version.
COMPOSE_FILE	/opt/balasys/etc/infrastructure/pas/docker-compose.yml or /opt/balasys/etc/infrastructure/mgmt/docker-compose.yml	Path to the compose file. You must not modify the default value.
COMPOSE_PROJECT_NAME	pas	Name used for the compose project. They must be kept synchronized over different files.
PAS_DOCKER_REGISTRY	docker.balasys.hu	It is the domain name of the docker registry to download images from.
MINIO_ACCESS_KEY		It is the access key to use for MinIO authentication. It is an arbitrary string preferably generated randomly. It must be the same in different files.
MINIO_SECRET_KEY		It is the secret key to use for MinIO authentication. It is an arbitrary string preferably generated randomly. It must be the same in different files.
CONSUL_HOSTNAME		It is the hostname or the IP address where Consul is accessible. Generally it should be the domain name or the IP address of the computer running PAS. The same value must be provided for this field in different files.
CONSUL_PORT	8080	It is the port to use for connecting to Consul. The same value must be provided for this field in different files.
CONSUL_TOKEN		The token to use for Consul authentication. The same value must be provided for this field in different files. It must also be the same as the value of `consul.master_token` in /opt/balasys/etc/mgmt/config.yml.

Table 2. docker-compose.conf configuration management-specific options
Key	Default	Description
PAS_MGMT_WEBUI_HTTP_PORT	80	It is the port to expose for HTTP access of the management web user interface.
PAS_MGMT_WEBUI_HTTPS_PORT	443	It is the port to expose for HTTPS access of the management web user interface.
MINIO_HOSTNAME		It is the hostname or IP address where MinIO is accessible. Generally it should be the domain name or IP address of the computer running PAS.
MINIO_PORT	9000	It is the port to use for connecting to MinIO.

Table 3. docker-compose.conf configuration core-specific options
Key	Default	Description
PAS_FLOW_DIRECTOR_SCALE	1	It defines the number of Flow Director instances to run. For details, see Scaling Flow Director.
PAS_TRANSPORT_DIRECTOR_PORT_RANGE1	49000-49100	It is a port range to expose to Transport Director. Listeners will work in this port range.
PAS_TRANSPORT_DIRECTOR_PORT_RANGE2	49101-49200	It is an additional port range to expose to Transport Director. Listeners will work in this port range.
MINIO_ENDPOINT		It is the host name (or IP address) and port pair to access MinIO. It must be defined in the `[hostname]:[port]` format.

Management example:

PAS_IMAGE_TAG=3.0.latest
COMPOSE_FILE=/opt/balasys/etc/infrastructure/mgmt/docker-compose.yml
COMPOSE_PROJECT_NAME=pas
PAS_DOCKER_REGISTRY=docker.balasys.hu

PAS_MGMT_WEBUI_HTTP_PORT=80
PAS_MGMT_WEBUI_HTTPS_PORT=443

MINIO_HOSTNAME=your.hostname.tld
MINIO_PORT=9000
MINIO_ACCESS_KEY=your_minio_access_key
MINIO_SECRET_KEY=your_minio_secret_key
CONSUL_HOSTNAME=your.hostname.tld
CONSUL_PORT=8080
CONSUL_TOKEN=your_consul_token

Core example:

PAS_IMAGE_TAG=3.0.latest
COMPOSE_FILE=/opt/balasys/etc/infrastructure/mgmt/docker-compose.yml
COMPOSE_PROJECT_NAME=pas
PAS_DOCKER_REGISTRY=docker.balasys.hu
PAS_FLOW_DIRECTOR_SCALE=1

PAS_TRANSPORT_DIRECTOR_PORT_RANGE1=49000-49100
PAS_TRANSPORT_DIRECTOR_PORT_RANGE2=49101-49200

MINIO_ENDPOINT=your.hostname.tld:9000
MINIO_ACCESS_KEY=your_minio_access_key
MINIO_SECRET_KEY=your_minio_secret_key
CONSUL_HOSTNAME=your.hostname.tld
CONSUL_PORT=8080
CONSUL_TOKEN=your_consul_token

Changing any of the values requires the restart of all services.

5.3. PAS restart policy

PAS service lifecycle is managed by systemd and is by default set to restart if any of the components fails at any point. To avoid infinite restarting, the number of restarts within a short period of time is also limited. As a result, if PAS core or management stops with a non-zero exit code 3 times within 100 seconds, the corresponding systemd unit will enter failed state.

The default restart policy and the options are identical for both core and management components.

The relevant part of the service file looks as follows:

[Unit]
StartLimitIntervalSec=100
StartLimitBurst=3

[Service]
Restart=on-failure

Modifying the restart policy is possible by editing the service file in override mode. To do so, run systemctl edit proxedo-api-security or systemctl edit proxedo-api-security-mgmt. This will open a text editor and will let you define the parameters you wish to override. For example, if you want to switch off all default restart settings, enter the following text in the override editing window:

[Unit]
StartLimitIntervalSec=
StartLimitBurst=

[Service]
Restart=no

Possible values for Restart= are documented by systemd. We recommend using no to avoid automatic restarting by systemd or on-failure to make the service restart on non-zero exit codes. If you want a more fine-tuned restart policy, please consult the systemd.service(5) man page and configure the desired options.

To discard your overrides, run systemctl revert proxedo-api-security or systemctl revert proxedo-api-security-mgmt.

You only need to enter the parameters you want to change.

Overriding systemd units is only possible as root user.

5.4. Tracking version

Proxedo API Security has a version number in the form of major.minor.patch. The docker image labels control how the automatic update of the services are handled. Each image has 3 possible tags:

MAJOR.latest (for eg. 1.latest): These tags point to the latest release in the major release. That is, for the release of both x.y.z+1 and x.y+1.0, this tag will be updated, and the services will be upgraded at the restarts. There will not be upgrades for x+1.0.0.
MAJOR.MINOR.latest (for eg. 1.3.latest): These tags point to the latest release in the minor release. That is, for the release x.y.z+1, this tag will be updated, and the services will be upgraded at restarts, however not for the release x.y+1.0.
MAJOR.MINOR.PATCH (for e.g. 1.4.7): These tags point to a specific release and will never be changed once released.

5.5. Scaling Flow Director

A single instance of Flow Director uses a single processor core. It is necessary to adjust the number of instances to use all the available cores. This is controlled by the PAS_FLOW_DIRECTOR_SCALE variable. As the Flow Director handles the most demanding duties among the components, it must be assigned most of the cores. If there are up to four cores available, assign three cores to the Flow Director, and the remaining one core will be suitable for the Transport and Insight Director. If there are more than four cores, assign two cores for the Transport and Insight Director and assign the rest to the Flow Director.

5.6. Configuration of dockerd

The docker daemon is configured through /etc/docker/daemon.json. The full documentation can be found in the official docker documentation.

Balasys recommends the use of the default configuration.

Do not use /etc/default/docker as it is ignored when systemd is used.

5.7. Setting up time synchronization

To ensure time synchronization on different nodes you need to configure NTP on them. The ntp package is already installed as a dependency, but it must be configured We recommend adding the following configuration to /etc/ntp.conf.

driftfile /var/lib/ntp/ntp.drift

restrict -4 default kod notrap nomodify nopeer noquery limited
restrict -6 default kod notrap nomodify nopeer noquery limited
restrict 127.0.0.1
restrict ::1

server time.nist.gov prefer
server ip-time-1.cern.ch

Use your own NTP servers in the server directives if you have any, or adjust the given values to ones that are allowed by your policies.

After creating the configuration, run the following commands.

# Disable systemd-timesyncd
timedatectl set-ntp false

# Restart ntp
systemctl restart ntp

# Enable ntp so that it starts on system startup
systemctl enable ntp

6. Configuration of Proxedo API Security on the Web User Interface

This chapter explains configuration details for setting up a working Proxedo API Security (PAS) with the help of the Web User Interface.

The Proxedo API Security Web User Interface (UI) is installed together with the installation of Proxedo API Security. The URL for Proxedo API Security Web UI and the necessary credentials are defined by the administrator during the initial configuration of Proxedo API Security.

6.1. Minimum configuration

It is possible to run PAS with a minimum, basic configuration. For a minimum configuration the following items need to be configured in the Web UI:

Listeners
- Port
- Endpoint
  For more details on the Listener's parameters, see Listeners’ configuration options.
Endpoint
- Name
- Url
  For more details on the Endpoint's parameters, see Endpoint configuration.
Security Flow
- Request
- Response
- Backend

This basic configuration can be further improved with the completion of more configuration units later. The minimum configuration can also be used to test the installation settings.

6.2. Login Page

The main component of the Login page is the login form where the user needs to provide the credentials in order to be authorized to use the Web UI of Proxedo API Security.

The necessary credentials have been defined during the initial configuration of Proxedo API Security.

For accessing the Web User Interface:

Enter the valid user credentials.
Click the Log In button.

After a successful login, the user has access to the Proxedo API Security Web UI.

6.3. Proxedo API Security Web User Interface main page

The configuration elements are organized into a logical order for easier usage.

Figure 4. Proxedo API Security Web User Interface main page

The PAS Web UI has the following navigation areas:

The navigation areas identified in Figure Navigation areas in the Proxedo API Security Web User Interface are described here in more details:

Left navigation area (1): This navigation area (1) presents the navigation units available for configuration.
When opening up the Proxedo API Security Web UI, three main navigation units are available, that is, BRICKS, PLUGINS, and SERVICES.
These three main navigation units can be opened for further sub-navigation units by clicking on either the navigation item itself or on the arrow icon next to it. Alternatively, when the sub-navigation units are not in use, they can be hidden by clicking the arrow navigation icons next to the main navigation items, or similarly by clicking on the navigation item itself.
Top navigation area (2): This Top navigation area (2) presents the Apply Config and the Logout options in the top right corner. For information on when and how to use the Apply Config button, see section Applying and validating Proxedo API Security configuration.

Main configuration area (3): This is the main configuration area of the Web UI. Any navigation unit selected in the Left navigation area (1) presents the configuration details in this Main configuration area (3). The configuration details can be edited in this area.
In case there are already configured parameters, those are displayed in a table in the Main configuration area (3).
In order to add more configuration details, select the New navigation button in the upper right corner.

The Main configuration area (3) provides the following navigation and activity options. Note that some of these activities are also available when the configuration parameters are presented in list view:

Table 4. Navigation and activity options in the Main configuration area (3)
Navigation option	Description
	By selecting the New navigation button, you can define a new configuration key, previously selected from the Left navigation panel (1) for configuration.
	By selecting the Pen navigation button, the Web UI navigates back to the configuration page of the selected element. You can change the so far configured details or add new configuration details. If you change the value of an already configured parameter, a Warning appears requesting confirmation on the change being implemented.
	By selecting the Bin button, you can delete the configuration element active in the window. If you select an element for deletion, a Warning appears, requesting confirmation on the deletion of the element.
	By selecting the Next page button you can navigate to the next page of the parameter keys listed.

6.4. BRICKS - Configuration units

Bricks are reusable components. They do not provide a complete security function themselves, instead, they are used as building blocks elsewhere (hence the name). They can be used by Plugins (like Selectors), or utilized by other bricks (like Extractors).

Certain Bricks are so called default objects, which are in 'read-only' state and cannot be configured or modified. Such default objects are listed in the following table:

Table 5. Default objects - BRICKS
Default object name	Class
Always	Matcher
Never	Matcher
content_type_json	Matcher
content_type_json_regexp	Matcher
json_content	Matcher
content_type_xml_base	Matcher
content_type_xml_dtd	Matcher
content_type_xml_ext_parsed	Matcher
content_type_xml_regexp	Matcher
content_type_xml_text	Matcher
content_type_xml_text_ext_parsed	Matcher
xml_content	Matcher
error_policy	Error policy
enforcer_default	Error policy
insight_default	Error policy

These default objects are listed under the actual classes in the Web UI.

The BRICKS main page in the Web UI is as follows:

Figure 6. Bricks' main page in the Web User Interface

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Click on the sub-navigation unit you would like to configure. The details of the sub-navigation menu open up in the Main configuration area.

6.4.1. Error Policy

Error Policies define how to proceed if a Plugin decides to have found an error. For example, when an Enforcer plugin decides that the call is invalid.

It is the error policy that enables the user to act differently in case the error appears in a request or a response.

6.4.1.1. Error policy hierarchy

Error policy values are applied in a hierarchical manner. There are three layers of definition:

the hard-coded default error policy (see the default values in Configuring Error policies)
the default error policy of the different Plugin types
These are needed because the expected default behavior depends on what a Plugin does.
a custom error policy applied on a Plugin instance that represents user policy

Error policies can behave differently when applied on different Plugins. This is because each Plugin has a default policy which can overwrite the settings defined in the applied error policy. Also, the plugin’s default policy is applied if there is no error policy configured. The effective error policy of each Plugin instance is logged when the Flow Director starts.

An error policy value is searched for in a bottom-to-top manner: if it is present in a custom error policy, it will be applied, if not, it will be looked for in the layer above.

This lookup works on a configuration item basis, therefore one can only override a single configuration in case of a custom error policy.

6.4.1.2. Configuring Error policies

Error policies can be configured from the BRICKS main menu item.

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Error Policy.

The configuration window that appears presents the default error policies, as listed in Default objects - BRICKS and the configuration values already set by the user:

Figure 7. Error policy’s main page in the Web User Interface

Click on the New navigation button to create an error policy.

An Error Policy contains the following settings:

Figure 8. Configuring error policies in the Web User Interface

The following table provides details on what values can be figured for an Error policy and what these values define for an Error policy. Configure the following options:

Table 6. Error policy configuration options
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		It is the name identifying the error policy. This name of the error policy can be referenced from other parts of the configuration, that is, the error policy is reusable.
Request	The available values are: abort log	Abort	It defines what action shall take place if there is an error on the request side: abort: the request is denied if the Plugin fails. Use the other parameters to control the content of the error sent to the client. log: the invalid requests are allowed, but are logged.
Request code	The values are available from a drop-down list. If the elements of the drop-down list are selected, it will make the list of the actual request codes visible. The applicable request code can be selected.	422	It provides the HTTP status code to be used when denying invalid requests.
Request message	The message can be provided in free text.	Request error	The reason is provided here in the HTTP response line when denying invalid requests.
Request silent	The parameter can be configured by switching it on or off. When it is switched on, the Plugins do not report on the denial of the invalid request. When it is turned off, the Plugins have the ability to report the error in detail in the body of the HTTP error request.	true	Do not report validation errors of the request to the client.
Response	Response error mode: abort log	Abort	It defines what action shall take place if there is an error on the request side: abort: the request is denied if the Plugin fails. Use the other parameters to control the content of the error sent to the client. log: the invalid requests are allowed, but are logged.
Response code	The values are available from a drop-down list. Note that the response codes are grouped, so that if the elements of the drop-down list are selected, further groups of response codes will be made visible in a tree structure. The applicable request code can be selected.	502	It provides the HTTP status code to be used when denying invalid requests.
Response message	The message can be provided in free text.	Response error	The reason is provided here that can be used in the HTTP response line when denying invalid requests.
Response silent	The parameter can be configured by switching it on or off. When it is switched on, the Plugins do not report on the denial of the invalid response. When it is turned off, the Plugins have the ability to report the error in detail in the body of the HTTP error response.	true	Do not report validation errors of the response to the client.

The default values in the above table represent the hard coded default values. They form a strict security policy: all errors are fatal, and only mistakes made by the client are reported in detail.

For configuring error policies, continue with completing the following steps:

Configure the necessary parameters for the error policy based on the details provided in the table Error policy configuration options.
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Click the Save button.

The default values in the above table represent the hard coded default values. They form a strict security policy: all errors are fatal, and only mistakes made by the client are reported in detail.

The error policies configured here can be used in the Plugin’s configuration, by referencing their name.

6.4.2. Matcher

Matchers decide if the Plugin should be executed for a given call by checking various data in the HTTP message. They provide an extremely versatile way of defining the circumstances that must be met for the Plugin to execute.

Matchers need three pieces of information:

Name: The name of the matcher defines what part of the call needs to be checked.
Pattern: The pattern defines what it needs to be compared with.
Comparator: The Comparator shows by what means the collected value of the call is compared with the provided pattern. (Some comparators also take flags or arguments.)

To ease configuration, a matcher in its simplest form is defined as a key: a value pair where the key contains the Name and the Comparator and the value is the pattern, as in the following example:

"name[.comparator[.comparator_flag][.comparator_flag]..]: pattern"

The matchers can be used in Plugin configurations' match option by referencing their name.

There are some named Matchers available without explicit configuration:

always and never are instances of Always matcher and never matcher.
json_content that matches requests with the Content-Type headers representing JSON.

Also note that no other matchers can be defined with these names.

Matchers internally utilize Extractors to fetch the information from the call to compare with. The Name of the matcher resembles the name of the extractor that will be used.

All matchers have a default comparator that is applied implicitly.

If you want to use comparator parameters, the comparator name should be given even if the default comparator is used.

6.4.2.1. Configuring Matchers

Matchers can be configured from the BRICKS main navigation item.

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Matcher.

The configuration window that appears presents the default matchers, as listed in Default objects - BRICKS and the configuration values already set by the user:

Figure 9. Matchers' main page in the Web User Interface

Click on the New navigation button to configure a matcher.

The generic configuration page for matchers provides the following settings:

Figure 10. Configuring matchers in the Web User Interface

The configuration parameters for matchers are described in details in the following table:

Table 7. Matcher configuration options
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		The name of the matcher defines what part of the call needs to be checked. Matchers internally utilize Extractors to fetch the information from the call to compare with. The Name of the matcher resembles the name of the extractor that will be used.
Type*	It is a mandatory value. For the available values, see Matcher types and their settings - Table 1, Matcher types and their settings - URI matchers - Table 2, Matcher types and their settings - Table 3 and Matcher types and their settings - Soap matchers - Table 4.		The preferred matcher type has to be selected from the drop-down list.

Provide the name of the matcher.
Choose the type of the matcher from the drop-down list.

Depending on the choice of the matcher type, some more required configuration fields might appear on this page. The following tables describe the matcher types in details and provide the necessary information for the additional configuration fields, required for setting the matcher types:

Matcher types and their settings - Table 1
Matcher types and their settings - URI matchers - Table 2
Matcher types and their settings - Table 3
Matcher types and their settings - Soap matchers - Table 4

Table 8. Matcher types and their settings - Table 1
Matcher type	Description
Always	This matcher always matches.
Never	This matcher never matches. It can be used to turn off a Plugin.
Method	It matches the HTTP method of the request. Note that the method is case insensitive by definition, therefore the case will always be ignored. When choosing the Method matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
JMESPath	It matches the data from the body of a JSON call with the help of the JMESPath expression. JMESPath is a query language for JSON. It is a very versatile tool for extracting the needed information from the body of the call, and for organizing it according to needs. A complete explanation on how to write JMESPath expressions is not in the scope of this document. To learn more about it visit the: main website: There is a tutorial. There are examples. There is also a formal specification. When choosing the JMESPath matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Raw content	It matches the original content of the message. If the content type is JSON, the body will be decompressed but not parsed. When choosing the Raw content matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Matcher type Description

URI matchers

A range of matchers is available to match different parts of the URI.

The structure of an URI looks as follows:

scheme://[username[:password]@]host[:port][/path][?query][#fragment]

That is, for example:

https://john.doe:secret123@example.com:8443/some/resource?foo=bar&baz=qux#some-anchor

The fragment part is used by the client locally, and is never sent in the HTTP requests, therefore the PAS cannot do anything with it.

These matchers use the URI extractors. It has an extensive list of examples of what each extractor extracts from the URI.

URI

It matches against the whole request URI as received from the client.

When choosing the URI matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI netloc

It matches the network location in the URI.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

If the port is the default port for the scheme — that is 80 and 443 for HTTP and HTTPS, respectively — the port will not be included, even if explicitly sent by the client. Therefore if the client used http://example.com:80/path, then the origin would be http://example.com, not http://example.com:80.

When choosing the URI netloc matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI origin

It matches the origin part of the URI.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

When choosing the URI origin matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI scheme

It matches the scheme of request (http or https). Note that the scheme is case insensitive by definition, therefore the case will always be ignored.

When choosing the URI scheme matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI username

It matches the username in the request if present.

When choosing the URI username matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI password

It matches the password in the request if present.

When choosing the URI password matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI host

It matches the host in the request.

When choosing the URI host matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI port

It matches the port of the request. Note that this matches the default port — that is 80 and 443 for HTTP and HTTPS, respectively — even if it is not explicitly in the request.

When choosing the URI port matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI path

It matches the path part of the URI.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

If you need to match the _path_ exactly as received, use URI raw path matcher.

When choosing the URI path matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI raw path

It matches the path part of the URI, without the normalization of URI path matcher carried out.

If the path is missing, the match still runs against a single forward slash ("/").

It is recommended to use URI path matcher unless there is an explicit need for matching the raw path. One such example would be logging or filtering out badly formed requests.

When choosing the URI raw path matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI raw query

It matches the query part of the URI as a string. It is recommended to use URI query parameter matcher unless there is an explicit need for matching the raw string. An example on this might be if there is a match on foo=barbar or tofoo=bar as well, even though it was not intended.

When choosing the URI raw query matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

URI query parameter

It matches the value of a query parameter.

It is also valid for URIs to include a query parameter more than once. That is, it could be foo=bar&qux=quz&foo=baz. To accommodate this, matching is done against the value of each occurrence of the parameter. Matching occurs if any value is matched.

When choosing the URI query parameter matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Matcher type Description

Header

It matches the value of an HTTP header. Some HTTP headers can be present more than once in a call. To accommodate this, matching is completed against the value of each occurrence of the header. Matching occurs if there is any match. For example, if the Accept header was repeated as follows:

Accept: application/json
Accept: application/xml

Consequently, in this example above both header.accept: application/json and header.accept: application/xml would match.

The syntax of this matcher differs from the others because the name of the Header name must be added:

"header.<header_name>[.comparator[.comparator_flag][.comparator_flag]..]"

Therefore to match against the header named Server the key will be header.server, possibly completed with comparator specification, like header.server.regex.ignorecase.

While the values are not, the HTTP header names are case insensitive, so you can write them all lowercase in the configuration key.

The syntax of this matcher differs from the others because the name of the Header name must be added.

While the values are not, the HTTP header names are case insensitive, so you can write them all lowercase in the configuration key.

When choosing the Header matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Content type

It matches the content type of the message. It is a more robust solution than using the Header matcher on the Content-Type header because that can contain parameters as well.

When choosing the Content type matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Status

It matches the status code of the response.

See the default Status class comparator which allows convenient matching on HTTP status classes.

The available values for the Expression parameter are: Informational response, Successful response, Redirects, Client errors, Server Errors.

When choosing the Status matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Call direction

Matches the direction of the message (request or response).

Any

Any is a Compound matcher that matches if any of its sub-matchers matches. The sub-matcher can also be a compound matcher.

All

All is a Compound matcher that matches if all of its sub-matchers match. The sub-matcher can also be a compound matcher.

None

None is a Compound matcher that matches if none of its sub-matchers match. The sub-matcher can also be a compound matcher.

One

One is a Compound matcher that matches if exactly one of its sub-matchers matches. The sub-matcher can also be a compound matcher.

xpath

It matches the data from the body of an XML call with the help of the Xpath expression.

Xpath is a query language for XML. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to needs.

A complete explanation on how to write Xpath expressions is not in the scope of this document. To learn more about it visit the main website.

For more details on xpath configuration options, see Xpath extractor configuration options.

When choosing the Call direction matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

Table 11. Matcher types and their settings - Soap matchers - Table 4
Matcher type	Description
Soap Matchers	A range of matchers is available to match different parts of the SOAP message. These matchers extend the [xpath-matcher] matcher with predefined expressions. They use the [soap-extractors]. It has an extensive list of examples of what each extractor extracts from the SOAP message. When choosing the SOAP Matchers matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap version	Soap version matches the soap message version. It identifies with the soap namespace. The possible values are: soapv1_1 - the message version is SOAP v1.1 soapv1_2 - the message version is SOAP v1.2 When choosing the SOAP version matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap envelope	It matches the soap envelope. When choosing the SOAP envelope matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap header	It matches the soap header. When choosing the SOAP header matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap body	It matches the soap body. When choosing the SOAP body matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap fault	It matches the soap fault. When choosing the SOAP fault matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap fault code	Soap matchers extend the xpath matcher with predefined expressions. They use the SOAP extractors. It has an extensive list of examples of what each extractor extracts from the SOAP message. It matches the soap fault 'code'. The expression depends on the soap version. faultcode - it is the SOAP v1.1 node tag. Code - it is the SOAP v1.2 node tag. When choosing the SOAP fault code matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap fault detail	It matches the soap fault 'detail'. The expression depends on the soap version. Detail - it is the SOAP v1.1 node tag. Detail - it is the SOAP v1.2 node tag. When choosing the SOAP fault details matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap 11 fault faultstring	It matches the soap fault 'faultstring'. This matcher only works with soap version 1.1. When choosing the Soap 11 fault faultstring matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap 11 fault faultactor	It matches the soap fault 'faultactor'. This matcher only works with soap version 1.1. When choosing the Soap 11 fault faultactor matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap 12 fault reason	It matches the soap fault 'Reason'. This matcher only works with soap version 1.2. When choosing the Soap 12 fault reason matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap 12 fault node	It matches the soap fault 'Node'. This matcher only works with soap version 1.2. When choosing the Soap 12 fault node matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.
Soap 12 fault role	It matches the soap fault 'Role'. This matcher only works with soap version 1.2. When choosing the Soap 12 fault role matcher from the drop-down list, additional parameters appear. For more information on the configuration of these parameters, see Matcher types' additional configuration options.

For details on comparator types, see Types of comparators.

Depending on the matcher type selected, the administrator might need to fill in further parameters. These parameters are described in the following table.

Table 12. Matcher types' additional configuration options
Key	Values	Default value	Description
Comparator			The matchers need the information on the Comparator, which shows by what means the collected value of the call is compared with the provided pattern.
Type	The available comparator types can be checked from the drop-down list.		For details on the comparator types, see Types of comparators.
Ignorecase		Off (False)	It sets the IGNORECASE flag for the selected comparator type.
Expression*			A regular expression specifies a set of strings that match it.
JmesPath Expression			A complete explanation on how to write JMESPath expressions is not in the scope of this document. To learn more about it visit the: main website: There is a tutorial. There are examples. There is also a formal specification.
Query Parameter			It is also valid for URIs to include a query parameter more than once. That is, it could be foo=bar&qux=quz&foo=baz. To accommodate this, matching is done against the value of each occurrence of the parameter. Matching occurs if any value is matched.
Header			It extracts the value of an HTTP header. It is valid for some HTTP headers to be present more than once in a call. In this case, all the values are extracted as a list. It provides the name of the header in the configuration.
Namespaces			It defines the XML namespaces.
Xpath Expression*			The expression to extract the node from the call to match against.
Multiline			It sets the Multiline flag for the Regex comparator.
Minimum*			It matches if the pattern is larger or equal to the value.
Maximum*			It matches if the pattern is smaller or equal to the value.

Configure the necessary parameters with the help of the above tables.
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Click the Save button to save the configured matcher.

6.4.3. Selector

Selectors are responsible for collecting information from the call. They utilize Extractor bricks for this purpose.

Most extractors return simple string values. However, some (might) return dictionaries. For example, you can get all the HTTP headers, or all the URI query parameters.

They are used by Insight.

6.4.3.1. Configuring Selectors

The selector can be configured from the BRICKS main navigation item.

Click on BRICKS main configuration item in the left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Selectors.

The configuration window that appears either presents the configuration values already set by the user or shows the configuration values ready to be configured:

Figure 11. Selector main page in the Web User Interface

Click on the New navigation button to configure the Selector.

The following configuration options appear for Selector:

Figure 12. Configuring Selector in the Web User Interface

The selector accepts the following configuration options:

Table 13. Selector configuration options
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		The name of the parameter can be referenced.
Type*	Choose the selector type from the drop-down list. For more details on the values, see Extractor types.		Extractors are used to extract data from the call. They are utilized by Selector (and Matcher as well). Extractors are included by their type in Selectors, and are used by a special syntax in matchers. For details, see Extractors and Extractor types.
Save as	The key under which the results of a selector are saved in the Insight plugin’s dictionary.	Top	If it is omitted, the result will be directly merged as top level keys.

Depending on what value is selected for the Type parameter, additional parameters might appear for configuration. The following table provides details on these additional parameters.

Table 14. Additional Selector configuration options
Key	Values	Default value	Description
Clear text	It can be switched On or Off.
Namespaces	It defines the XML namespaces.
Xpath Expression			The expression to extract the node from the call to match against.
JmesPath Expression			A complete explanation on how to write JMESPath expressions is not in the scope of this document. To learn more about it visit the: main website: There is a tutorial. There are examples. There is also a formal specification.
Expression*			A regular expression specifies a set of strings that match it.
Time format*	'YYYY-MM-DDTHH:mm:ss.SSSSSSZZ'	Set the format. See: Timestamp format options
Time zone*			It is the name of the time zone, or the time zone offset. The time zone can be specified by using the name, for example, "Europe/Budapest", or as the time zone offset in +/-HH:MM format, for example, +01:00).

Name the Selector key.
Fill in any more desired parameters.
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Click the Save button if you have configured all the required parameters.

6.4.4. Target

Target bricks define where the data collected by the Insight will be sent to.

The Target configuration tree contains named Targets with their respective configuration.

Unlike other bricks, target configurations cannot be put inline into a Plugin’s configuration, they must always be configured here.

See the Target configuration options for the available target types and their configuration options.

6.4.4.1. Data flattening

To ensure compatibility with a wide range of target types, the results collected by the Insight plugin are flattened. The path inside the complex data structure is encoded into the key for each value:

The merged key describes the path to the value in the data structure as a string.
The parts of the path will be separated by a forward slash character ("/").
Keys in nested dictionaries are added to the path by name.
List items are added to the path by their index.

You can control the separator with the Flatten separator configuration key that every target accepts.

6.4.4.2. Configuring Targets

The Target can be configured from the BRICKS main navigation item.

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Target.

The configuration window that appears either presents the configuration values already set by the user or shows the configuration values ready to be configured:

Figure 13. Target main page in the Web User Interface

Click on the New navigation button to configure the Target.

Figure 14. Configuring Target in the Web User Interface

The Target accepts the following configuration options:

Table 15. Target configuration options
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		It is the name identifying the Target. This name of the Target can be referenced from other parts of the configuration.
Type*	It is a mandatory value. The values can be selected from the drop-down list. The available values are: Local log Syslog Elastic		Local log: It logs the result of the insight in the local system log. For more details on configuration settings with Local log, see Local log Target configuration parameters. Syslog: It sends the insight to a remote syslog server using the IETF syslog protocol defined in RFC5424. For more details on configuration settings with syslog, see table Syslog Target configuration parameters. Elastic: It sends the insight to an Elasticsearch engine in JSON. For more details on configuration settings with syslog, see Elastic Target configuration parameters.
Flatten	This parameter can be switched 'on' or 'off'.	On (True)	Flatten the target message.
Flatten separator		/	It is the separator in the flattened message.
Level		3	It is the log level for the logged message.
Message		It is the message of the insight if present, otherwise it is empty.	It is the message part of the log message.
Tag	The value can be selected from a drop-down list.	info	It is the log tag for the logged message.

Provide the name for your Target configuration.
Select the Target type.
Continue with the Syslog, Elastic and Local log configurations with the help of the following tables: Syslog Target configuration parameters, Elastic Target configuration parameters and Local log Target configuration parameters.

The following table presents the configuration parameters for the Local log Target type:

Table 16. Local log Target configuration parameters
Key	Default value	Description
Flatten separator	/	It is the separator in the flattened message.
Level	3	It provides the log level for the logged message.
Message	The message of the insight if present, otherwise it is empty.	It is the message part of the log message.
Tag	info	It is the log tag for the logged message.

The following table presents the configuration parameters for the syslog Target type:

Table 17. Syslog Target configuration parameters
Key	Values	Default value	Description
Data format	The possible values are: sdata, json.	sdata	This is the data format of the insight.
Enable heartbeat		False	It enables sending heartbeat (-- MARK --) messages to the target.
Flatten		True	It flattens the target message.
Flatten Separator		/	It is the separator in the flattened message.
Flush lines			It specifies how many lines are flushed to a destination at a time. The Insights Director waits for this number of lines to accumulate and sends them off in a single batch. Increasing this number increases the throughput, as more messages are sent in a single batch, but also increases the message latency.
Heartbeat	Frequency: A number greater than or equal to 1. Mode: The possible values are: 'idle' (heartbeat messages are only sent when there is no traffic towards the target) and 'periodical' (heartbeat messages are sent regardless of activity).	Frequency: 30 Mode: 'periodical'	Frequency: The number of seconds between heartbeat messages. Mode: The operation mode of the heartbeat functionality.
Host*			It is the hostname of the syslog search instance.
IP protocol	The possible values are 4 and 6, corresponding to IPv4 and IPv6.		This determines the internet protocol version of the given driver.
Mask credit card numbers		False	It masks the middle section of recognised credit card numbers in any fields of the log message. Recognised credit cards are from one of the following issuers: American Express, Discover Card, Mastercard, VISA.
Remote Connection	Protocol: The available values are: TCP and UDP. Port: The available values are: 514 for TCP and 601 for UDP. Use TLS: The available values are True or False. Syslog TLS: Select the Syslog TLS* brick you want to use for the target.	Protocol: TCP Port: 514 Use TLS: False	Protocol: Add the transport protocol to send messages over. The available values are: TCP and UDP. Port: Add the port number here to connect to the remote system. Use TLS: It enables using TLS for the Syslog communication. Syslog TLS: It is mandatory if the Use TLS* option is set to True.
Report config load		False	It reports the event of a configuration being loaded with a cryptographic hash of the loaded configuration. This ingorms the target about changes in the configuration.
Second fraction digits	Integer between 0 and 6 inclusive	3	The number of digits representing the fractions of seconds in the Syslog timestamp.
Time Zone	See table Time zones for time zone names.	GMT	The name of the time zone (for example, "Europe/Budapest") or the time zone offset in +/-HH:MM format (for example, +01:00).

The following table presents the configuration parameters for the elastic Target type:

Table 18. Elastic Target configuration parameters
Key	Values	Default value	Description
Doc type		_doc	The doc type is used when sending the data.
Flatten		True	It flattens the target message.
Flatten Separator		/	It is the separator in the flattened message.
Host*			It is the hostname of the Elastic search instance.
Index			It is the name of the index in the Elastic search instance.
Mask credit card numbers		False	It masks the middle section of recognised credit card numbers in any fields of the log message. Recognised credit cards are from one of the following issuers: American Express, Discover Card, Mastercard, VISA.
Port	514 for TCP 601 for UDP		Add the port number here to connect to the remote system.

Configure any more desired parameter details.
Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Click Save to save your configuration settings for the Target.

6.4.5. TLS

Transport Layer Security (TLS) is the cryptographic protocol that secures HTTPS communications. PAS can apply TLS encryption both when communicating with Clients and Backends.

When HTTPS is used the TLS settings must be configured.

These parameters are used by the Transport director. For options that reference a file the path is relative to /opt/balasys/var/persistent/ inside the Transport Director container. This directory is a docker volume and by default mounted from the /opt/balasys/var/persistent/transport-director directory in the host system.

6.4.5.1. Configuring the TLS

TLS can be configured from the BRICKS main navigation item.

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select TLS.

The configuration window that appears either presents the configuration values already set by the user or shows the configuration values ready to be configured:

Figure 15. TLS main page in the Web User Interface

Click on the New navigation button to configure TLS.

TLS contains the following settings:

Figure 16. Configuring TLS in the Web User Interface

The configuration of the first two parameters determines the TLS type and from these two steps on, it is either a Client TLS configuration or a Backend TLS configuration.

6.4.5.1.1. Configuring the Client TLS

The following parameters need to be configured for Client TLS:

Configuring TLS in the Web User Interface TLS options

Figure 17. Configuring Client TLS in the Web User Interface, TLS options

Configuring TLS in the Web User Interface Certificate options

Figure 18. Configuring Client TLS in the Web User Interface, Certificate options

Name the Client TLS configuration.
Select the Type of the TLS, Client TLS in this case, from the drop-down list to configure TLS.

For details on these parameters, see the following table:

Table 19. TLS configuration
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		The name of the parameter can be referenced.
Type*	It is a mandatory value. Choose the required value from the drop-down list.		Client TLS, Backend TLS and Syslog TLS configurations can be defined here.

Configure the mandatory parameters for Client TLS, based on the information provided in Table Client TLS configuration.

Table 20. Client TLS configuration
Key	Values	Default value	Description
Certificate*			Configuration for the X.509 certificate used for TLS connections on the listener.
Certificate File*	It is a mandatory value. You can upload the certificate file.		Provide the path and filename for the certificate file. The certificate must be in PEM format.
Key file*	It is a mandatory value. You can upload the key file.		Provide the path and filename to the private key file. The private key must be in PEM format.
Key passphrase	You can upload the file.		Provide the passphrase used to access the private key specified in the Key file.
Enable Verification*		Off (False)	It is an option for verifying client side X.509 certificates. By default no client verification takes place.
Client verification*			Client verification options
Trusted Certs	You can upload trusted certificates in a ZIP file.		A directory where trusted IP addresses, certificate assignments are stored. When a peer from a specific IP address shows the certificate stored in this directory, it is accepted regardless of its expiration or issuer CA. Each file in the directory should contain a certificate in PEM format. The filename must be the IP address.
Required	The parameter can be switched on or off.	On (true)	If it is set to True, PAS requires a certificate from the peer.
Trust Level	The values can be selected from the drop-down list. The available values are: none untrusted full	full	It defines the trust level for certificate verification: none: Accept even invalid certificates, for example self-signed certificates. untrusted: Both trusted and untrusted certificates are accepted. full: Only valid certificates signed by a trusted CA are accepted.
Verify Depth		4	It defines the length of the longest accepted CA verification chain. PAS will automatically reject longer CA chains.
Ca Dir	You can upload the trusted CAs in a ZIP file		It is a Directory where where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.
Verify Crl	The parameter can be switched on or off.	Off (false)	If it is set to True, PAS checks the CRLs (Certificate Revocation Lists) associated with trusted CAs. CRLs will load automatically if PAS verifies the certificate of the peer.
Intermediate Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	hard_fail	The revocation check type for all certificates in the chain, except the Leaf Certificate: none: Ignore the result certificate revocation status check soft_fail: It fails if the check is successful and the certificate is revoked, it will pass otherwise hard_fail: It passes only if the check is successful and the certificate is not revoked
Leaf Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	hard_fail	The revocation check types for the Leaf certificate are as follows: none: With this option the result of the certificate revocation status check is ignored soft_fail: It fails if the check is successful and the certificate is revoked, it passes otherwise hard_fail: It passes only if the check is successful and the certificate is not revoked
Options*			TLS protocol options used on the listener.
Disable TLS v1	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	On (true)	Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.
Disable TLS v1.1	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1.1 in the connection.	On (true)	It does not allow the usage of TLSv1.1 in the connection.
Disable TLS v1.2	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1.2 in the connection.	Off (false)	It does not allow the usage of TLSv1.2 in the connection.
Disable TLS v1.3	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1.3 in the connection.	false	It does not allow the usage of TLSv1.3 in the connection.
Cipher		ECDHE-ECDSA-AES128-GCM-SHA256: ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-GCM-SHA384: ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY1305: ECDHE-RSA-CHACHA20-POLY1305: DHE-RSA-AES128-GCM-SHA256: DHE-RSA-AES256-GCM-SHA384	Specifies the allowed ciphers. Can be set to all, high, medium, low, or a string representation of the selected ciphers.
Timeout	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	300	It drops idle connection if the timeout value (in seconds) expires.
Session Cache Size	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	20480	It defines the number of sessions stored in the session cache for SSL session reuse
Disable Session Cache	The parameter can be switched on or off.	Off (false)	Do not store session information in the session cache. Set this option to 'on' to disable SSL session reuse.
Disable Ticket	The parameter can be switched on or off.	Off (false)	Do not store session information in the session cache. Set this option to 'on' to disable SSL session reuse.
Disable Compression	The parameter can be switched on or off.	Off (false)	Set the parameter On to disable support for SSL/TLS compression. Set the parameter Off to enable support for SSL/TLA compression.
Cipher Server Preference	The parameter can be switched on or switched off.	On (true)	Use server and not client preference order when determining which cipher suite, signature algorithm or elliptic curve to use for an incoming connection.
Disable Renegotiation	The parameter can be switched on or off.	On (true)	Set this parameter On to disable client-initiated renegotiation.
Dh Parameter File			You can upload the DH parameter file. The DH parameter file must be in PEM format.

Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Save the Client TLS configuration by clicking Save.

6.4.5.1.2. Configuring Backend TLS

The following parameters need to be configured for Backend TLS:

Figure 19. Configuring Backend TLS in the Web User Interface, TLS options

Figure 20. Configuring Backend TLS in the Web User Interface, Certificate options

Name the Backend TLS configuration.
Select Backend TLS from the drop-down list to configure Backend TLS.

For details on these parameters, see the following table:

Table 21. TLS configuration
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		The name of the parameter can be referenced.
Type*	It is a mandatory value. Choose the required value from the drop-down list.		Client TLS, Backend TLS and Syslog TLS configurations can be defined here.

Configure the mandatory parameters for Backend TLS, based on the information provided in Table Backend TLS configuration.

The configuration parameters are described in details in the following table:

Table 22. Backend TLS configuration
Key	Values	Default value	Description
Enable Certificate*		Off/False	It is an option for enabling backend side X.509 certificates. By default no backend verification takes place.
Enable Verification*		Off/False	It is an option for verifying Backend side X.509 certificates. By default no backend verification takes place.
Backend verification*			Backend verification options
Trusted Certs	You can upload trusted certificates in a ZIP file.		A directory where trusted IP addresses-certificate assignments are stored. When a peer from a specific IP address shows the certificate stored in this directory, it is accepted regardless of its expiration or issuer CA. Each file in the directory should contain a certificate in PEM format. The filename must be the IP address.
Trust Level	The values can be selected from the drop-down list. The available values are: none untrusted full	full	It defines the trust level for certificate verification: none: Accept even invalid certificates, for example self-signed certificates. untrusted: Both trusted and untrusted certificates are accepted. full: Only valid certificates signed by a trusted CA are accepted.
Verify Depth		4	It defines the length of the longest accepted CA verification chain. PAS will automatically reject longer CA chains.
Ca Dir	You can upload the trusted CAs in a ZIP file.		It is a directory where the trusted CA certificates are stored. CA certificates are loaded on-demand from this directory when PAS verifies the certificate of the peer.
Verify Crl	The parameter can be switched on or off.	Off (false)	If it is set to True PAS checks the CRLs (Certificate Revocation Lists) associated with trusted CAs. CRLs will load automatically if PAS verifies the certificate of the peer.
Intermediate Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	soft_fail	The revocation check types for all certificates in the chain, except for the Leaf Certificate are as follows: none: If this options is set, the certificate revocation status check results are ignored soft_fail: If this option is set, the certificate revocation check fails, if the check is successful and the certificate is revoked. The check passes otherwise. hard_fail: If this option is set, the check passes only if the check is successful, and the certificate is not revoked.
Leaf Revocation Check Type	The values can be selected from the drop-down list. The available values are: none soft_fail hard_fail	soft_fail	The revocation check type for the Leaf Certificate. none: The result of the Certificate Revocation Status Check is ignored. soft_fail: If this option is set, the certificate revocation check fails, if the check is successful and the certificate is revoked. The check passes otherwise. hard_fail: If this option is set, the check passes only if the check is successful, and the certificate is not revoked.
Check Subject	The parameter can be switched on or off.	Off (false)	If it is set to, PAS compares the subject of the server-side certificate with application-layer information (for example, it checks whether the Subject matches the hostname in the URL).
Options*			TLS protocol options used on the listener.
Disable TLS v1	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	On (true)	Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.
Disable TLS v1.1	The parameter can be switched on or off. If it is set ON it does not allow using TLS v. 1.1 in the connection.	On (true)	It does not allow the usage of TLS v. 1.1 in the connection.
Disable TLS v1.2	The parameter can be switched on or off. If it is set ON it does not allow using TLS v. 1.2 in the connection.	false	It does not allow the usage of TLS v. 1.2 in the connection.
Disable TLS v1.3	The parameter can be switched on or off. If it is set to ON it does not allow using TLS v. 1.3 in the connection.	false	It does not allow the usage of TLS v. 1.3 in the connection.
Cipher		ECDHE-ECDSA-AES128-GCM-SHA256: ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES256-GCM-SHA384: ECDHE-RSA-AES256-GCM-SHA384: ECDHE-ECDSA-CHACHA20-POLY1305: ECDHE-RSA-CHACHA20-POLY1305: DHE-RSA-AES128-GCM-SHA256: DHE-RSA-AES256-GCM-SHA384	Specifies the allowed ciphers. Can be set to all, high, medium, low, or a string representation of the selected ciphers.
Timeout	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	300	It drops idle connection if the timeout value (in seconds) expires.
Session cache size	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	20480	It defines the number of sessions stored in the session cache for SSL session reuse
Disable session cache	The parameter can be switched on or off.	Off (false)	Do not store session information in the session cache. Set this option to 'On' to disable SSL session reuse.
Disable ticket	The parameter can be switched on or off.	Off (false)	Do not store session information in the session cache. Set this option to 'On' to disable SSL session reuse.
Disable compression	The parameter can be switched on or off.	Off (false)	Set the parameter On to disable support for SSL/TLS compression. Set the parameter Off to enable support for SSL/TLA compression.

Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Click the Save button if you have configured all the required parameters.

6.4.5.1.3. Revocation checks for certificates

The PAS tries both CRL and OCSP-stapling checks for certificates.

The result for a certificate according to the revocation check types:

Table 23. Certificate revocation checks
CRL check	OCSP stapling check	Soft fail result	Hard fail result
PASS	PASS	PASS	PASS
PASS	unsuccessful	PASS	PASS
unsuccessful	PASS	PASS	PASS
unsuccessful	unsuccessful	PASS	FAIL
PASS	FAIL	FAIL	FAIL
FAIL	PASS	FAIL	FAIL
unsuccessful	FAIL	FAIL	FAIL
FAIL	unsuccessful	FAIL	FAIL
FAIL	FAIL	FAIL	FAIL

6.4.5.1.4. Configuring Syslog TLS

The following parameters need to be configured for Syslog TLS:

Figure 21. Configuring Syslog TLS in the Web User Interface

Name the Syslog TLS configuration.
Select the Type of the TLS, Syslog TLS in this case, from the drop-down list to configure TLS.

For details on these parameters, see the following table:

Table 24. TLS configuration
Key	Values	Default value	Description
Name*	It is a mandatory value. It can be defined in free text.		The name of the parameter can be referenced.
Type*	It is a mandatory value. Choose the required value from the drop-down list.		Client TLS, Backend TLS and Syslog TLS configurations can be defined here.

Configure the mandatory parameters for Syslog TLS, based on the information provided in Table Syslog TLS configuration.

Table 25. Syslog TLS configuration
Key	Values	Default value	Description
Certificate*			It is the configuration for the X.509 certificate used for TLS connections on the target.
Certificate File*	It is a mandatory value. You must select a File brick of type generic that represents the uploaded certificate.		Provide the name of the selected File brick. The certificate must be in PEM format.
Key file*	It is a mandatory value. You can select a File brick of type generic that represents the uploaded private key.		Provide the name of the selected File brick. The private key must be in PEM format.
Enable Verification*		Off (false)	It is an option for enabling the verification of server side X.509 certificates.
Options*			TLS protocol options used on the Syslog target.
Disable SSL v2	The parameter can be switched on or off.	On (true)	Session tickets are a method for SSL session reuse, described in RFC 5077. Set this option to ON to disable SSL session reuse using session tickets.
Disable SSL v3	The parameter can be switched on or off.	On (true)	Session tickets are a method for SSL session reuse, described in RFC 5077. Set this option to ON to disable SSL session reuse using session tickets.
Disable TLS v1	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1 in the connection.	On (true)	Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.
Disable TLS v1.1	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1.1 in the connection.	On (true)	It does not allow the usage of TLSv1.1 in the connection.
Disable TLS v1.2	The parameter can be switched on or off. If it is set ON it does not allow using TLSv1.2 in the connection.	Off (false)	It does not allow the usage of TLSv1.2 in the connection.
ECDH curve list	Add one or more names of ECDH curves. The possible values are the ones supported by OpenSSL 1.1.1.	Off (false)	This is a list of curves permitted in the connection when using Elliptic Curve Cryptography (ECC).
Peer verify	Select one of the following options in the drop-down menu: optional-trusted, optional-untrusted, required-trusted, required-untrusted	required-trusted	It defines the verification method of the peer. The four possible values are a combination of two properties of validation: whether the peer is required to provide a certificate (required or optional prefix), and whether the certificate provided needs to be valid (trusted or untrusted suffix).
Cipher	It is the colon-separated list of ciphers from the list supported by OpenSSL 1.1.1.	ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:!aNULL:!MD5:!DSS!aNULL: !MD5: !DSS	It specifies the allowed ciphers.
DH Parameter File	Select a File brick of type generic from the drop-down menu.		It specifies the file containing the Diffie-Hellman parameters, generated using the `openssl dhparam` utility. It must be in PEM format.
Server verification*			Server verification options are mandatory if Enable Verification is set to True.
Trusted DN	It is a list of the distinguished names of the accepted certificates.		You can list the distinguished names of the accepted certificates in this parameter to accept connections only from hosts using certain certificates signed by the trusted CAs. For example, when using ", O=Example Inc, ST=Some-State, C=", it will accept only certificates issued for the Example Inc organization in Some-State state.
CA dir	Select the CA File brick representing your CA directory.		CA directory containing the trusted CA and CRL files.
Verify CRL		Off (false)	It verifies that certificates used in the connection are not revoked by any CRLs in the CA directory.

Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Save the Syslog TLS configuration by clicking Save.

6.4.6. Files

The Files configuration element enables the administrator to upload any Generic, Swagger, XSD, WSDL, CA and CRL certificate files.

6.4.6.1. Configuring Files

Files can be configured from the BRICKS main navigation item.

Click on BRICKS main configuration item in the Left navigation area. Alternatively you can also click on the sign to open up the sub-navigation items of BRICKS.
Select Files.

The configuration window that appears either presents the configuration values already set by the user or shows the configuration values ready to be configured:

Figure 22. Files main page in the Web User Interface

Click on the New navigation button to configure Files.

Files contains the following settings:

Figure 23. Configuring Files in the Web User Interface

Files has the following configuration parameters:

Table 26. Files configuration parameters
Key	Values	Description
Name*	It is a mandatory value. The name can be provided in free text.	It defines the file-related configuration.
Type*	It is a mandatory value. The available values are: Generic Swagger XSD WSDL CA CRL See table Requirements for specific file types for specific requirements for each type.	The type selected here defines by which BRICK it can be used. The file uploaded here with the Type Swagger, for example, can be used by Swagger bricks.
File*	It is a mandatory value. The required file can be uploaded here.

Click the Validate button to check if the defined parameters are suitable and adequate for configuring the component. If the configuration of the component is erroneous or not adequate, the Web UI provides a warning that the 'Component validation failed'. Also a warning with information on the missing details appears at the problematic field for the user. If the configuration of the component is satisfactory, after clicking the Validate button, the user receives the 'Component Validation successful' notification.
Save the configuration by clicking the Save button.

Table 27. Requirements for specific file types
File type	Requirements
CA	It must be a flat ZIP file with the CA certificates inside. It must contain not only the certificate files but also copies of them named following the `<hash>.0` format. The value of the `<hash>` part can be produced with the following command: `openssl x509 -noout -hash -in /path/to/cert/file`. It can contain CRL files, but then it also needs to contain the copies of them following the `<hash_of_the_related_ca_file.r0` format. The hash can be produced as described above.

6.4.7. Common configuration elements for BRICKS

6.4.7.1. Extractors

Extractors are used to extract data from the call.

They are utilized by Matcher and Selector. Extractors are configured as part of matchers and selectors, there are no named extractors.

Extractors are included by their type in Selectors, and are configured within matchers.

Most extractors return simple string values. However, some (might) return dictionaries. For example, you can get all the HTTP headers, or all the URI query parameters.

See the Extractor types for more details on extractors and their configuration options.

The following table provides details on extractor types:

Key Description

Method

It extracts the HTTP method of the request. It does not require configuration.

Status

It extracts the status code of the response. It does not require configuration.

JMESPath

It extracts data from the body of a JSON call with the help of a JMESPath expression.

JMESPath is a query language for JSON. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to requirements. A complete explanation on how to write JMESPath expressions is not in the scope of this document.

To learn more about it visit the: main website:

There is a tutorial.
There are examples.
There is also a formal specification.

Header

It extracts the value of an HTTP header. It is valid for some HTTP headers to be present more than once in a call. In this case, all the values are extracted as a list. It provides the name of the header in the configuration.

Header force list

It works like the Header extractor but it returns a list even if there is only a single extracted value.

Header first

It works like header extractor but it only returns the first extracted value even if there is a list of extracted values.

Headers

It extracts all the headers from the call. The results are stored as a dictionary, therefore it is recommended to omit the 'save as' key if you use this from a selector. It is valid for some HTTP headers to be present more than once in a call. In such cases all the values are stored under the header’s key as a list. It does not require configuration.

URI

It matches against the whole request URI as received from the client. It does not require configuration.

URI netloc

It extracts the network location in the URI. It does not require configuration.

It includes:

username and password if present
host
port if present unless scheme default

If the port is the default port for the scheme — that is 80 and 443 for HTTP and HTTPS, respectively — the port will not be included even if explicitly sent by the client. So if the client used http://example.com:80/path then the netloc would be example.com, not example.com:80.

URI origin

It extracts the origin part of the URI. It does not require configuration.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

URI scheme

It extracts the scheme of the request (http or https). It does not require configuration.

URI username

It extracts the username in the request if present. It does not require configuration.

URI password

It extracts the password in the request if present. It does not require configuration.

URI host

It extracts the host in the request. It does not require configuration.

URI port

It extracts the port of the request, the default port — that is 80 and 443 for HTTP and HTTPS, respectively — even if it is not not displayed explicitly in the request. It does not require configuration.

URI path

It extracts the path part of the URI. It does not require configuration.

It includes:

scheme
host
port if present, unless the default port for the scheme is used

If you need to extract the path exactly as received, use URI raw path parameter.

URI raw path

It extracts the path part of the URI, without the normalization of URI path carried out.

NOTE: If the path is missing a single forward slash ("/") is extracted.

It does not require configuration.

URI raw query

It extracts the query part of the URI as a string. It does not require configuration.

It does not require configuration.

URI query

It extracts the query part of the URI. It does not require configuration.

It does not require configuration.

URI query parameter

It extracts the value of a query parameter. It is also valid for URIs to include a query parameter more than once. That is, it could be 'foo=bar&qux=quz&foo=baz'. In this case both values are extracted as a list. Provide the name of the parameter in the configuration.

URI query parameter force list

It works like Uri query parameter but it returns a list even if there is only a single extracted value.

URI query parameter first

It works like Uri query parameter but it only returns the first extracted value even if there is a list of extracted values.

Content

It extracts the content. It does not require configuration.

Raw content

It extracts the content as a string. It does not require configuration.

Content type

It extracts the content type from the HTTP header. It does not require configuration.

Content type charset

It extracts the charset from the content type HTTP header. It does not require configuration.

Call direction

It extracts the call direction (request, response). It does not require configuration.

Session ID

It extracts the internal identifier of the HTTP session in keep-alive HTTP connections. Its 'Include request counter' option enables adding a request counter representing the number of requests in the session.

Static

It extracts a string, integer, number, object, array, boolean as string from the configuration.

Timestamp

It extracts the current time. Also see the tables on Configuring timestamps and Timestamp format options.

Xpath

It extracts data from the body of an XML call with the help of a Xpath expression.

Xpath is a query language for XML. It is a very versatile tool for extracting the needed information from the body of the call, and organizing it according to needs.

A complete explanation on how to write Xpath expressions is not in the scope of this document. To learn more about it visit the main website.

Also see table Xpath extractor configuration options.

Provide the Xpath expression in the configuration. Depending on the expression, the return value is a single node or a list of nodes. If you want a single value or a list independent from the expression, use xpath first or xpath force list.

Xpath force list

It works like xpath but it returns a list even if there is only a single extracted value.

Xpath first

It works like xpath but it only returns the first extracted value even if there is a list of extracted values.

Soap version