REST API GUIDE

What is the REST API?

Using the REST API, Endpoint Privilege Management data can be configured, customized, and retrieved by other software. The API is web-based and uses industry standard modern components, connectors, and data elements within a distributed and secure enterprise environment.

The API can be used with Endpoint Privilege Management for Unix and Linux v7.1.0 and later.

How do I access it?

The REST API is bundled with the main installation and configured in pbinstall:

15  Install REST Services?         [yes]
72  REST Service installation directory?       [/usr/lib/beyondtrust/pb/rest]

The menu response shown above installs the REST API web server components. When installing any server components, REST API installation becomes mandatory.

73  Install REST API sample code?  [yes]
74  REST API sample code directory?            [/usr/local/lib/pbrest]

The menu response shown above installs the Java and scripting example code.

Architecture overview

Authentication

REST is a stateless protocol, which is strongly stressed and adhered to, and so every call must authenticate to the REST service. EPM-UL REST API uses an authentication method developed by Amazon Web Services that uses a pre-shared key and HMAC signature.

An Application ID, devised by the administrator, is input into a key store maintenance program that stores the ID alongside a randomly generated Application Key, and specified ACLs that specify the access the Application ID has. The Application Key is output, and these two together form the authentication mechanism.

The Application ID and a timestamp (epoch seconds) of information are hashed together using the Application Key to make an MD5 HMAC signature that is appended onto the URL of each call. It checks the timestamp to make sure it is relatively recent, retrieves the Application ID, and produces the HMAC using the same parameters to make sure the authentication is valid. The key store is encrypted by default, and can be relocated using configuration in pb.settings.

Installation and configuration

The REST API is bundled in tar files and package installers.

Prerequisites

• A suitable web server that supports Fast CGI protocol, configured to support Fast CGI modules and HTTPS/SSL (with a suitable certificate). This includes the enabling of any firewalls to allow HTTPS access.
• Endpoint Privilege Management for Unix and Linux v7.1.0 or above preinstalled and configured.
• Root access on the host that will provide REST API to enable the installation of the module.
• For development with the Java example sources, a Java 7 JDK is required, and the Eclipse IDE project files are provided for convenience.

The REST API must be installed on different Endpoint Privilege Management for Unix and Linux hosts, based on the functionality required:

REST API installed files

ℹ️

Note

tempfilepath defines a temporary path to be used as the temporary filesystem for EPM-UL binaries. The default is set as /tmp. At install time, if pbinstall is invoked, using -t option, tempfilepath is set to . lockfilepath defines a lock file path for EPM-UL binaries as needed. The default is /opt/pbul/locks.

When REST API is installed, the following files are copied to the host:

• The binary pbrestcall is copied to the Administration Program Location (/usr/sbin, by default ).
• The binary pbconfigd is copied to WWW server CGI directory specified during the installation.
• The sample code files are copied to the REST API sample code directory specified during the installation:
  • examples/lighttpd/: Example configuration files for lighttpd. The contents of these are referenced below in the example configuration of web server
  • examples/java/: Java sources and Eclipse project for Java API examples
  • examples/java/PBULAPI/build.xml: Ant build script to build the Java .jar
  • examples/java/PBULAPI/doc: Javadoc documentation
  • examples/jsoncalls.html: Example of static HTML file, containing JavaScript implementation of JSON API. The file contains JavaScript sections that implement the MD5 HMAC required to make the REST call.
  • examples/java/PBULAPI/test: JUnit test suite to test all areas of the JSON REST API using Java
  • examples/java/PBULAPI/src/*: The Java example source to call the REST API
  • examples/scripts/: Example bash scripts that implement JSON API calls

pblighttpd service

pblighttpd is the HTTP server daemon which launches the REST service. It is configured to run as a service in the background on hosts where an Endpoint Privilege Management for Unix and Linux server component is installed.

After a successful installation, the pblighttpd service is configured to startup and shutdown:

• systemd/xinetd/init on Linux
• init on HP-UX
• inittab for AIX
• SMF for Solaris 10+

Stop pblighttpd

When pblighttpd service receives a stop request, its main process ensures all child processes have terminated before it exits. This feature, combined with a lock file mechanism, helps prevent a new set of processes from starting before the old set has cleaned up and exited.

Start pblighttpd

The pblighttpd service is comprised of a set of processes which is monitored by a parent process. A lock file mechanism is used to ensure that only one set exists at a time.

To avoid running out of resources during heavy load while support authentication events to a program (eventdestinations authevt=|program), pblighttpd-svc must be started with unlimited NOFILES and NPROC, at least. For example, on Linux with systemd:

# cat /etc/systemd/system/pblighttpd.service
[Unit]
Description=BeyondTrust Privilege Management - REST Server
After=network.target
[Service]
Type=forking
Environment=LD_LIBRARY_PATH=/opt/pbul/rest/lib:/opt/pbul/lib:/usr/lib/oracle/19.5/client64/lib
ExecStart=@/opt/pbul/rest/sbin/pblighttpd-svc pblighttpd-svc -d -i xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ExecReload=/bin/kill -HUP $MAINPID
TasksAccounting=false
LimitNPROC=infinity
LimitNOFILE=infinity
LimitCORE=infinity
[Install]
WantedBy=multi-user.target

For legacy sysV, add ulimit -u unlimited and ulimit -n unlimited to the start routine of /etc/rc.d/init.d/pblighttpd.

Restart pblighttpd when pb.settings changes

The pblighttpd service must be restarted when the following keywords are changed in pb.settings:

• svccacherefresh
• dbsyncrefresh
• pblicenserefresh
• autofwdtime
• iologactioninterval
• sharedlibssldependencies
• sharedlibcurldependencies
• schedulingservice
• restservice
• pbrestlog
• messageroutersocketpath
• messagerouterqueuesize

pblighttpd_svc.sh

pblighttpd_svc.sh is a wrapper script that can start, stop, and restart pblighttpd on any of the supported platforms. It is installed in the same location as the other EPM-UL administration programs.

Syntax

<prefix>pblighttpd_svc.sh<suffix> <action>

where <action> is one of the following:

• stop: Stop the pblighttpd service
• start: Start the pblighttpd service
• restart: Stop and then start the pblighttpd service

When used to stop the pblighttpd service, the script ensures that all the processes associated with pblighttpd have terminated before exiting and returning to the command prompt.

ℹ️

Note

On systems where processes take a long time to exit, the script may appear hung when it is just waiting for a child process. Use ps or a similar tool to list running processes and check for pblighttpd.

When being requested to start the pblighttpd service, the script errors out if it detects that a pblighttpd service is already running.

The script uses the pbdbutil (pbadmin) option to check if pblighttpd and pbconfigd processes are accepting requests before attempting to stop or restart.

<prefix>pbdbutil<suffix> --info --restsvr

If not accepting requests, the script displays “The process does not seem to accept requests, attempting to <stop/restart> anyway” to inform you of current status but proceeds with stopping or restarting the service anyway.

API programs

pbconfigd

• Version 8.5.0 and earlier: pbconfigd setting not available
• Version 9.0.0 and later: pbconfigd setting available

The pbconfigd binary is used by the pblighttpd process to provide REST services. Functionality provided by newer versions of EPM-UL uses facilities the REST services provide:

• Secure communication between services across the enterprise
• A reliable replicated database layer
• Scheduled tasks that provide automated maintenance and housekeeping for background processes,
• The REST API layer used by the BeyondInsight for Unix & Linux GUI management tool, and can be used by customers to integrate EPM-UL with their own in-house processes and systems.

pbconfigd is launched by the pblighttpd server and communicates in JSON over the FastCGI protocol.

• The service is started automatically by the operating system and services requests when various other facilities of EPM-UL require it.
• Primary servers instantiate more pbconfigd processes so that they can more readily serve secondary servers and clients with services such as Registration Name Service, Role Based Policy configuration, File Integrity Monitoring, and Licensing framework.
• Client hosts do not generally run pbconfigd processes, but can momentarily launch the service to allow client configuration or to retrieve valuable data for the BeyondInsight for Unix & Linux management GUI.

As more Endpoint Privilege Management for Unix and Linux facilities become more reliant upon the REST service for reliable and successful functioning, it is vital to make sure that the service is working correctly. We recommend the REST log file be closely monitored and the troubleshooting guide used whenever issues are noted.

Generally pbconfigd is launched automatically by the pblighttpd service and should not be launched manually.

ℹ️

Note

pbconfigd has a --call option. This action requires a JSON string parameter to process and processes as if the call was made over REST. This allows specific calls that are required to action licensing and message router queuing calls to be made.

Usage

pbconfigd [options]
    -v, --version
    --help

Arguments

pbrestcall

• Version 8.0 and earlier: pbrestcall setting not available
• Version 8.1.0 and later: pbrestcall setting available

The pbrestcall utility provides a method of making REST API calls from the command line. It calculates the MD5 HMAC of the header to provide authentication, and encodes command line parameters on the URL.

Example

pbrestcall -l -a appid -k f339c33b-64d7-44f4-b113-34e344cff670 https://myhost:24351/REST/settings

This retrieves and display all of the /etc/pb.settings from the Policy Server host using the REST API, and the -l parameter lists them in a formatted JSON format.

Usage

pbrestcall [options] [param=value param=value…]
    -a <appId> [<acl> ...]
    -k <appKey>
    -d
    -X
    -l
    -v
    -t
    -p

The URL with HMAC and timestamp can be printed using the -p parameter. MD5 HMAC along with timestamp (see the setting pbresttimeskew) authenticates the session.

pbrestcall -p -l -a appid -k f339c33b-64d7-44f4-b113-34e344cff670 https://myhost:24351/REST/settings

Response https://myhost:24351/REST/settings?appid=appid×tamp=1620676163&hmac=9623fe94d48e50d2d600efd518613392

Arguments

Configure pbconfigd FastCGI module

The pbconfigd specific parameters below may need to be added to /etc/pb.settings manually.

restkeyencryption

• Version 8.0 and earlier: restkeyencryption setting not available
• Version 8.1.0 and later: restkeyencryption setting available

This is similar to other encryption keywords but only takes one value at a time.

restkeyencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]

Example

restkeyencryption aes-256:keyfile=/etc/pb.key

Default

restkeyencryption aes-256

Used on

• All hosts where pbconfigd is installed

pbrestlog

• Version 8.0 and earlier: pbrestlog setting not available
• Version 8.1.0 and later: pbrestlog setting available

This option configures where the pbconfigd binary should log debug and error messages.

Example

pbrestlog /var/log/pbrest.log

Default

Depending on the operating system standards, this can be any of the following:

• /var/log/pbrest.log
• /var/adm/pbrest.log
• /usr/adm/pbrest.log

Used on

All hosts where pbconfigd is installed

pbrestkeyfile

• Version 8.0 and earlier: pbrestkeyfile setting not available
• Version 8.1.0 and later: pbrestkeyfile setting available

This option allows the specification of where the pbconfigd keys are kept. This keystore is encrypted using the restkeyencryption option above. It may be written as an absolute path, or a path relative to the databasedir setting.

Example

pbrestkeyfile /mypath/pbrstkeys.db

Default

pbrestkeyfile /opt/pbul/dbs/pbrstkeys.db

Used on

All hosts where pbconfigd is installed

REST ACL’s

To allow different applications to have different access over the REST API, ACLs can be created against given application ID’s. These take the form of regular expressions that match specific REST API URLs. Each application ID can have up to 8 regular expressions assigned to it.

Examples

Configure pbconfigd keystore

To enable the authentication of REST API sessions pre-shared keys are created with application identifiers. These are used to identify the application and to create a MD5 HMAC (along with a timestamp) to authenticate the session.

Example

The following is an example of the most basic configuration:

pbdbutil --rest -g appid

This creates an application ID of appid and displays the application key, which needs to be noted, as it cannot be retrieved and added to the web application.

Specify a REST URL path and parameters

RESTful interfaces use the URL path to specify data and attributes, not actions.

• Actions are specified using the HTTP request methods GET, PUT, POST, and DELETE.
• Data is grouped together in the URL path. For example all EPM-UL settings are specified in the path /REST/settings (or /REST/setting when accessing a single setting).
• HTTP GET requests always pass parameters (URL encoded) as URL parameters on the URI. PUT, POST, and DELETE can use either the URI or the HTTP body to pass more complicated data.

Example

To retrieve the iolog /tmp/iolog+root.log:

GET https://<host>:<port>/REST/iolog?file=%2f/tmp%2fiolog%2broot%2elog

Example

To overwrite the pb.settings parameter submitmaster:

PUT https://<host>:<port>/REST/setting/submitmaster
{ "setting": {"values":["pbuild","pbuild2","pbuild3"]}}