OpenPMF REST API

Version 1.0 - December 2018 - © ObjectSecurity LLC - all rights reserved - questions? contact us

Overview

OpenPMF contains a number of restful APIs for accessing its capabilities as a SaaS (Software as a Service) model.

The APIs available are:

Only one API call may be active at any one time. An API status API is available to determine if another call is active. If an API is called while another is running it will fail and end immediately. See API Status below.

The path listed in the specific API descriptions is to be prefaced with https://domain:port/api for the OpenPMF installation being utilized, e.g. https://openpmf:9889/api/fsd/application/. The trailing slash is required.

REST APIs use part of their calling URL to pass and set parameters. These can be used to engage unique behaviors or pass identifying information.

Return Format

Every OpenPMF API call returns JSON as the body of the return.

One of two JSON properties will always be present in the top level JSON properties, error and response. If error is present, then the call failed in some way. The value of the property contains a readable error string. Otherwise response will be present, with a value of “OK”.

Other JSON properties may be present, and depend on the specific API called. These are detailed in the specific API documentation that follows.

API Status

The API status API works with all of the other APIs to serialize API calls. Only one call may be ‘active’ at a time. If a second API call is made, it will fail.

The API status API may be called to determine if OpenPMF is busy handling another call.


/status/

HTTP type: GET

This API is used to determine whether OpenPMF is busy handling another API request.

The return JSON has the following two properties session and busy. If busy is ‘true’ (note its a String) then OpenPMF will not be able to respond to another API call. The session property contains a description of the current call being handled.

Application Policy APIs

A set of three APIs are provided to support access to OpenPMF’s application policy capabilities. See the ClientSDK documentation for more information on these services. The SDK provides higher level access and support to applications working with this feature of OpenPMF.

These are documented together here because they work with each other to provide the full ‘round trip’ of rights matrix generation for a client application. These three APIs are used by the ClientSDK library.

These three API are also distinct in that they incorporate additional security for data integrity across the call.

Each of these calls is checked for an API key in the request header named ‘OPMF-API-Key’. The key is a SHA-256 hash of the caller’s public encryption key. The API code runs through its public key store on each call, hashes each and compares that to the API key. If one public key matches, the call is accepted, if not, the call excepts and ends.

In addition, the payloads of these API call are signed. The API code verifies the included payload signature with the public key that was verified against API key above. A supporting Java class, named KeyWorks.java, available in the ClientSDK library, can be used to created the signed request.


/fsd/application/

HTTP type: POST

This API is used to import an application specification, or feature matrix, provided by an application client. The body of the call contains the specification in JSON format.


/policy/llp/application/{id}/

HTTP type: POST

This call has OpenPMF generate the rights matrix for the identified application specification id. The matrix is cached in OpenPMF’s src-gen folder with the name ‘application.{id}.json’. {id} is to be replaced by the node id desired from the application specification. See the ClientSDK documentation for more information.

The rights matrix may be optionally requested to be returned upon completion. The body of the call has a single property JSON content. The property is called return. If it’s value is true the API call will return with the rights matrix as JSON in the body of the call return. Example:

{'return': true}

/policy/export/application/{id}/

HTTP type: GET

This API will return the complete rights matrix for the application id specified, if available.

The body of the call return contains the rights matrix in JSON format. Note: this is an exception to the standard API return body format discussed above, if the call succeeded.

The same is true for the previous API, if matrix return is requested.

CSVP APIs

This set of APIs allow management and upload of CSVPs (content value set providers).


/csvp/

HTTP type: GET

This API call returns a list of all available CSVPs in a JSON array property named csvps. Each entry has two properties: name and id. name is the name of the CSVP and id is its id, which is its index in the list.


/csvp/{id}/

HTTP type: GET

This API call returns the name of the identified CSVP in a property named name.


/csvp/{id}/values/

HTTP type: POST

This API call generates a calculation of the identified CSVP. The contents of the specified CSVP are compiled. It does not return any unique properties.

Feature Manager APIs

This set of APIs allow retrieval and management of OpenPMF feature details and enablement.

These APIs enable the Marketplace feature of OpenPMF, also available under its own tab in the main user interface.


/features/

HTTP type: GET

This API call returns an array of available features as a JSON array property named features.

Each feature has the following properties and JSON structure:

{  
   "wiped":false,
   "background":"Cyan",
   "name":"dds_importer_dds_exporter",
   "logo":"images/omgdds_logo.png",
   "links":{  
      "DDS Discovery Dump JAR":"ddsdiscoverydump.jar"
   },
   "id":0,
   "title":"OMG Data Distribution Services (DDS)",
   "enabled":true,
   "props":[  
      "DDS attribute, policy & data query setup",
      "Import OpenPMF DDS Discovery Dump",
      "Export OMG compliant permission & governance"
   ]
}

The properties are as follows.


/features/id/{id}/

HTTP type: GET

This API call returns the feature data of the specified feature index in a property called featureData. Format is the same as a single item from the array above.


/features/id/{id}/

HTTP type: POST

This API is used to enable or disable OpenPMF features.

This API is called with three properties, feature, enable and wipe. feature is the identifier of the feature to work with. The value of enable will enable or disable the feature in OpenPMF, and the value of wipe indicates whether to remove any user-added feature properties.

There are no special return properties.

FSD Import APIs

These APIs send data scans to OpenPMF as functional system description (FSD) imports.


/fsd/dds/

HTTP type: POST

This API allows the import of data description services (DDS) discovery dumps. The DDS dump is sent as JSON as the full body of the message with three properties, data, importer and version. data contains the dds dump xml as text. importer is ‘dds’ and version is 1.0.


/fsd/tcpdump/

HTTP type: POST

This API allows the import of TCP monitoring dumps. The TCP dump is sent as JSON as the full body of the message with three properties, data, importer and version. data contains the tcp dump as a text string. importer is ‘tcpdump’ and version is 1.0.

High Level Policy API

This API call generates a human readable version of the high level OpenPMF access control policy set and returns it.


/policy/hlp/{format}/

HTTP type: GET

If {format} is ‘text’, a plain text version of the policy set is returned. If {format} is ‘html’, a browser readable html version of the policy set is returned. In both cases, if successful, the return message body is the entire returned file. This is an exception to the standard return format, for a successful retrieval.

Low Level Policy Generation API

This API call generates all low level policy sets.


/policy/llp/

HTTP type: POST

There are no additional returned properties…

Policy Export APIs

These APIs are used for listing and retrieving available files generated in process by OpenPMF.


/policy/export/

HTTP type: GET

This API call returns an indexed list (JSON array) with the names of all available export files in a property named files. Not strictly necessary, but the size of the list is available in a separate property named size.


/policy/export/{id}/raw/

HTTP type: GET

This call returns the file identified by id, which is its index in the file list above. The body of the call return is the raw text of the requested file. This is an exception to the standard return format if the call is successful.


/policy/export/all/zip/

HTTP type: GET

This call returns all files available zipped together in a single file. The body of the call return is the raw bytes of the entire zipped file, and the return mime type is set to application/zip. Most browsers will recognize this and ask to save the zip to disk.

This is an exception to the standard return format if the call is successful.

Template API

This API works with and allows retrieval of templates from OpenPMF.


/template/

HTTP type: GET

Returns a JSON array list of all template names available from OpenPMF, in a property called templates. The size of the list is in a property named size.


/template/{id}/

HTTP type: GET

Returns template details of the identified template. {id} is the index of the template of interest from the list above. Returned is information about the template in four properties. name, id, templateidentifier, and importertag with values for those properties of the template.


/template/{id}/

HTTP type: POST

The identified template is selected for merge and then executed. {id} is the index of the template of interest from the list above.

Workflow APIs

These APIs allow the execution of an arbitrary series of OpenPMF API calls. A workflow may be predefined as a template and hosted on OpenPMF. These templates can be retrieved and populated for specific use. Custom workflows may be executed as well, if they follow the proper JSON structure (example shown below).


/workflow/

HTTP type: GET

Returns a JSON array list of all workflow template names available from OpenPMF, in a property called templates. The size of the list is in a property named size.


/workflow/id/{id}/

HTTP type: GET

Returns the workflow template of the identified template. {id} is the index of the workflow template of interest from the list above. Returned is the requested workflow template JSON in a property named json.

Example template:

{
   "name":"OpenPMF Workflow Triple",
   "lastModified":123098109239,
   "type":"ImpGenDwn",
   "steps":[{
      "data":"",
      "name":"Co.com intranet TCP",
      "step":"import",
      "api":"fsd/tcpdump/",
      "type":"tcp",
      "return":"none"
   },{
      "data":"",
      "name":"Wednesday's TCP Session",
      "step":"import",
      "api":"fsd/tcpdump/",
      "type":"tcp",
      "return":"none"
   },{
      "data":"",
      "name":"DDS bldg 1 import",
      "step":"import",
      "api":"fsd/dds/",
      "type":"dds",
      "return":"download"
   },{
      "data":"",
      "name":"Generate all from DDS",
      "step":"generate",
      "api":"policy/llp/",
      "type":"all",
      "return":"none"
   }]
}

This example workflow template has four steps, three imports, two tcp and one dds, and an llp generate at the end. Each step is a JSON object with six properties. These are detailed as follows:

A custom workflow can be created by following the structure of this example template.


/workflow/

HTTP type: POST

This API executes the workflow passed in as the body of the POST. The call is synchronous and only returns on completion of all API steps, or error.

Returned is standard response with no custom properties.