REST API

Introduction

A REST API is available to allow Privilege Management data to 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 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.

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

REST services are not fully supported on macOS.

Architecture Overview

A diagram of the REST API process flow in Privilege Management for Unix and Linux.

Functionality

Settings

  • Get All Settings: Gets all of the settings from pb.settings (or equivalent). Each setting has one of 4 distinct types:
    • String
    • Boolean
    • List of Strings
    • altsubmitmasters: Has a special list of Privilege Management for Unix and Linux objects
  • Get Individual Settings: Gets an individual setting as specified on the URL.
  • Put Setting: Puts (modify) a setting into the pb.settings file. The type must correspond to the original setting type.
  • Get Settings file as attachment: Retrieves the whole pb.settings file as a binary attachment.

License

  • License Get: Retrieves the text value of the license.

Policy

  • Policy List Dir: Lists all of the files in a given directory (without checking if they are iologs). This would be limited to policydir if defined. Some system directories cannot be listed for security.
  • Policy (Script) Get Lines: Gets a script-based policy file as an ordered array of lines, making line based modifications to the policy file easier.
  • Policy (Script) Get Full File: Gets the full script-based policy file as a long string.
  • Policies (CSV) Get All: Retrieves an array of CSV policies. Elements are generally strings or arrays of strings.
  • Policy (CSV) Get (by name): Retrieves a given named CSV policy.
  • Policy (CSV) Put (by name): Puts a given CSV policy, named on the URL.
  • Policy (Script) Set New Policy File: Creates a new (optionally empty) policy script file. Directory is limited by policydir if it is set. Parent directories are not created.
  • Policy check: Checks policy in a similar manner to pbcheck.
  • Get Policy file as attachment: Retrieves a full policy file as a binary attachment.

IO Logs

  • IO Log Get: Retrieves an IO log file. Output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
  • IO Log List Dir: Lists all of the files in a given directory (without checking if they are IO logs). Filter can be specified as a regular expression to filter output. Some system directories cannot be listed for security.
  • IO Log Get Variables: Retrieves the log variables from the specified IO log.
  • Get IO Log file as attachment: Retrieves an IO log file as a binary attachment.
  • IO Log search: Searches a list of IO logs, specified with a glob style wildcard parameter file, for the query string <query>. This is a similar format to the SOLR search string in which you have a regular expression query, with keyword:value values. For example, stdout:.*inittab searches for any IO logs that incorporate the word inittab in the output. All of the standard keyword values that can be extracted from IO logs can be used in the search criteria. Regular expression matches are not made across newlines.
  • IO Log Replay: Retrieves and interprets an IO log file ready to be output by a GUI. Override terminal emulation using the parameter term, and the output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
  • IO Log Get: Retrieves an IO log file. Output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
  • IO Log List Dir: List all of the files in a given directory (without checking if they are IO logs). Filter can be specified as a regular expression to filter output. Some system directories cannot be listed for security.
  • IO Log Get Variables: Retrieves the log variables from the specified IO log.
  • Get IO Log file as attachment: Retrieves an IO log file as a binary attachment.
  • IO Log search: Search a list of IO logs, specified with a glob style wildcard parameter file, for the query string <query>. This is a similar format to the SOLR search string where you have a regular expression query, with keyword:value values. For example, stdout:.*inittab searches for any IO logs that incorporate the word inittab in the output. All of the standard keyword values that can be extracted from IO logs can be used in the search criteria. Regular expression matches are not made across newlines.
  • IO Log Replay: Retrieves and interprets an IO log file ready to be output by a GUI. Override terminal emulation using the parameter term, and the output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.

Event Logs

  • Event Log Get: Retrieves the specified event log.
  • Get Event Log file as attachment: Retrieves the specified event log as a binary attachment.

Key File

  • Key Get: Gets the specified pb.key file as a base64 encoded string.
  • Key Set: Sets the specified pb.key to the base64 encoded string.
  • Create a new key: Creates a new specified pb.key file and generates random contents.
  • Get Key file as attachment: Retrieves the specified pb.key file as a binary attachment.

SOLR

  • Solr Get: Retrieves SOLR search results based upon the supplied criteria.

Authentication

REST is a stateless protocol, which is strongly stressed and adhered to, and so each and every call must authenticate itself to the REST service. Privilege Management for Unix and Linux REST API will use 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 what 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.

REST API is not fully supported on macOS.

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.
  • 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 Privilege Management for Unix and Linux hosts, based on the functionality required:

REST API Call Privilege Management Component Requiring REST API Installation
Get License Policy Servers
Get/Put Policy Policy Servers
Get/Put Settings The local host where the settings need to be read/written to
Get/Search/List iologs Log Servers
Get Eventlogs Log Servers
Get/Create keyfile Policy Servers
Solr search Any host

REST API Installed Files

tempfilepath defines a temporary path to be used as the temporary filesystem for PMUL binaries. The default is set as /tmp. At install time, if pbinstall is invoked, using -t <tempdir> option, tempfilepath is set to <tempdir>. lockfilepath defines a lock file path for PMUL 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

For more information on pbrestcall and pbconfigd, please see pbrestcall and pbconfigd.

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 a Privilege Management for Unix and Linux server component is installed. After a successful installation, the pblighttpd service is configured to startup and shutdown via init on Linux/HP-UX, inittab for AIX, and SMF for Solaris 10+.

Stop pblighttpd

Platform Command
Linux service pblighttpd stop
HP-UX /sbin/init.d/pblighttpd stop
AIX stopsrc -s pblighttpd
Solaris svcadm disable pblighttpd

Start pblighttpd

Platform Command
Linux service pblighttpd start
HP-UX /sbin/init.d/pblighttpd start
AIX startsrc -s pblighttpd
Solaris svcadm enable pblighttpd

You can also restart pblighttpd using the pblighttpd_svc.sh script. The script simply restarts pblighttpd without having to remember how to start the service on different platforms.

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

When required, <action> is one of the following: start, stop, or restart.

This script uses pbdbutil/pbadmin option to check to see if pblighttpd/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 user of current status but proceeds with stopping or restarting the service anyway.

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, simply add ulimit -u unlimited and ulimit -n unlimited to the start routine of /etc/rc.d/init.d/pblighttpd.

Restart pblighttpd when pb.settings is changed

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

Privilege Management for Unix and Linux REST 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 utilized by the pblighttpd process to provide REST services. Much of the functionality that is provided by newer versions of Privilege Management for Unix and Linux uses facilities that the REST services provide. These include 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 Privilege Management for Unix and Linux 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 Privilege Management for Unix and Linux require it. Primary servers tend to 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 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.

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.

pbconfigd [options]
	-v, --version
	--help
-v, --version Optional. Display version and exit.
--help Optional. Display this help message and exit.

For more information, please see pblighttpd Service.

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.

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.

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&timestamp=1620676163&hmac=9623fe94d48e50d2d600efd518613392
-a <appId> Mandatory. Specify Application ID to use.
-k <appKey> Mandatory. Specify Application Key to use.
-d HTTP body data as a string, or - to use stdin
-X HTTP request method. GET, PUT, POST, DELETE.
-l Long (pretty print) JSON
-v Verbose
-t Debug
-p Print the URL and exit

Configuration of 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>]
restkeyencryption aes-256:keyfile=/etc/pb.key
restkeyencryption aes-256
  • All hosts where pbconfigd is installed

For more information, please see networkencryption.

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.

pbrestlog /var/log/pbrest.log

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

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.

pbrestkeyfile /mypath/pbrstkeys.db
pbrestkeyfile /opt/pbul/dbs/pbrstkeys.db

All hosts where pbconfigd is installed

REST ACL’s

To allow different applications to have different access over the REST API, ACLs have been implemented and 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.

GET:/settings Allow retrieval of any settings
PUT:/settings Allow the change of any settings
\(GET\|PUT\):/setting/\ (submitmaster\|acceptmasters\) Allow the modification of submitmaster and accepmasters
GET:/iolog/.*file=\%2Ftmp\%2F.* Allow the retrieval of any iolog in /tmp

Configuration of 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.

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, so for example all Privilege Management for Unix and Linux 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.

To retrieve the iolog /tmp/iolog+root.log:
GET https://<host>:<port>/REST/iolog?file=%2f/tmp%2fiolog%2broot%2elog
To overwrite the pb.settings parameter submitmaster:
PUT https://<host>:<port>/REST/setting/submitmaster
{ "setting": {"values":["pbuild","pbuild2","pbuild3"]}}