Overview

In a typical deployment on Linux or Solaris, the process for the API Gateway instance runs as root.
This is typically used to enable the process to listen on Internet domain privileged ports (port numbers
less than 1024). However, this is a potential security issue because the root user has read/write
access to all files on the system. Therefore, if the API Gateway process ever becomes compromised, it could
be used to return the contents of, or overwrite sensitive files, and the operating system would not
prevent this. A solution to this problem is to run the API Gateway as a non-root user, but still allow the
API Gateway process to bind to privileged ports.

Important

The steps in this topic apply to the following API Gateway processes:

API Gateway instance

Admin Node Manager

API Gateway Analytics

Linux capabilities

Traditional UNIX implementations distinguish between the following categories of processes:

privileged processes whose effective user ID is 0
(superuser or root)

unprivileged processes whose effective user ID is non-zero

Privileged processes bypass all kernel permission checks where unprivileged processes are subject to full
permissions checking based on the processes credentials, usually from the effective user ID and effective
group ID. More recent versions of the kernel divide up the privileges traditionally associated with the
superuser into a set of capabilities that can be independently enabled or disabled. This
allows a more fine-grained control of permissions for a process.

The capability to use with the API Gateway is CAP_NET_BIND, which specifically allows binding to
privileged ports. The method by which this capability is set on the API Gateway is supported from kernel
2.6.24 onwards. If the kernel version is before 2.6.33, you must enable
CONFIG_SECURITY_FILE_CAPABILITIES.

Before you begin

The sections that follow describe the steps that you must perform to run the API Gateway as an unprivileged
user. This topic assumes that the new unprivileged user is named admin, and that the location
of your API Gateway installation is /home/admin/apigateway.

Modify API Gateway file ownership

The unprivileged user must have ownership of the API Gateway files. If there is a pre-existing API Gateway
installation, you must change the ownership of the API Gateway files to the new user that you intend to
run the API Gateway with.

You can use the following command to change the user and group ownership of all files under the
installation directory:

# chown -R user:usergroup /path/to/apigateway/installation

For example:

# chown -R admin:admin /home/admin/apigateway

SSL accelerators for HSM

When using a Hardware Security Module (HSM), the unprivileged user must have access to the device
corresponding to the crypto accelerator or HSM card. For HSMs such as Cavium and Ultimaco, this
means that you must have access to the following directories:

Cavium: /dev/pkp_nle_drv

Utimaco: /dev/cs2a

For example, when using Cavium, an admin user using /dev/pkp_nle_drv
should have the following permissions:

crw-rw-r-- 1 root admin 126, 0 /dev/pkp_nle_dev

If the unprivileged user is different from admin, run the following command:

To verify that the permission has been set, run the following command:

# getcap /home/admin/apigateway/platform/bin/vshell

For example, the output of this command should be as follows:

/home/admin/apigateway/platform/bin/vshell = cap_net_bind_service+ep

Note

For API Gateway versions prior to 6.3.0 (for example, 6.1.2), this path should be
platform/libexec/vshell instead of platform/bin/vshell.

Install the libcap2 package if required

Depending on your Linux distribution, this may involve installing an additional software package.
If the setcap command cannot be found, try installing the libcap2 package.

For yum-based systems (for example, Redhat Enterprise Linux, CentOS, Oracle Enterprise Linux),
you can use the following command:

# yum install libcap2

For Debian or Ubuntu, you can use the following command:

# apt-get install libcap2-bin

API Gateway appliance version 7.1.0 or later

You must set an additional privilege for API Gateway appliance version 7.1.0 or later. This step
applies if you have an appliance and wish to run the vshell processes as a user other
than the default admin user.

Add API Gateway library locations

When executing a file with elevated permissions, certain environment variables are disabled as a security
precaution. For this reason, you must make the locations of the API Gateway library files available to the
operating system. You can do this using the steps described in this section:

You should replace /home/admin/gateway with the root of your API Gateway
installation.

Run ldconfig

After creating the /etc/ld.so.conf.d/gateway-libs.conf file, run the following
command to reload the library cache file:

# ldconfig

Modify the init.d script to use sudo

If there is an init.d script that runs the API Gateway as a service, you must change this
to execute as the unprivileged user. The easiest way is by using sudo -u admin in the
start command of the script.

For API Gateway version 6.1, this means changing the following line in the /etc/init.d/vordelgateway
script: