IRI DarkShield-RDB RPC API
IRI DarkShield Version 5 includes a Remote Procedure Call (RPC) Application Programming Interface (API) for searching and masking data stored in relational databases.
This API can be used within applications you write, or directly from IRI Workbench jobs you configure graphically. Outside Workbench, you can embed the API as middleware in a (e.g. CI/CD) pipeline. Within Workbench, you can specify and export its search and mask contexts through the New Relational DB Search/Masking Job wizard.
The DarkShield-RDB API can support any relational database for which a JDBC driver is provided. It is built as a plugin atop the IRI Web Services Platform (codenamed Plankton), which allows you to pick which services you require while utilizing the same hosting, configuration, and logging capabilities provided through the platform.
Before continuing with this article, please familiarize yourself with the operations of the DarkShield-Files API in this article and the base DarkShield API in this article.
The DarkShield-RDB API utilizes the DarkShield-Files API to handle binary data, and the base DarkShield API to handle non-binary values extracted from columns in tables.
All demos associated with this article can be downloaded from our Git repository here. To run the demos, you will need a working copy of the DarkShield-RDB API hosted locally on your computer. Contact your IRI representative for a trial copy of the software.
RDB Search Contexts
The RDB API introduces an extension to the File Search Context, an RDB Search Context, for defining search criteria for a relational database. The following snippet of the OpenAPI definition shows the structure of its schema:
The RDB Search Context uses a name attribute to uniquely identify a context for performing search operations. The fileSearchContextName attribute indicates a File Search Context that will be associated with the RDB Search Context. There is also a configs attribute used to pass parameters related to connecting and interacting with a relational database.
RDB Mask Contexts
The RDB API introduces an extension to the File Mask Context, an RDB Mask Context, for defining search criteria for a relational database. The following snippet of the OpenAPI definition shows the structure of its schema:
The RDB Mask Context name attribute uniquely identifies the context when performing masking operations. The fileMaskContextName attribute indicates the File Mask Context that will be associated with the RDB Mask Context. There is also a configs attribute used to pass parameters for connecting and interacting with a relational database.
RDB Search Configs
| Key Name | Description | Optional or Required | |
| Schema | schemaName | The name of the schema. | Required |
| URL | url | URL for JDBC connection. | Required |
| User | username | The username. | Optional |
| Password | password | The password. | Optional: if authenticating password is required. |
| Regex Include | includePattern | Only tables that match based off of a Java regex pattern inside a schema will be searched. | Optional |
| Regex Exclude | excludePattern | Tables that do not match based off of a Java regex pattern inside a schema will be searched. | Optional |
| Fetch Size | fetchSize | Dictates how many rows to handle per batch. Default value is 1024. Expects an integer. | Optional |
| Driver Configurations | driverConfigs | Additional JDBC driver options. Key Value pairs with string values expected. | Optional |
| Driver Class | driverClassName | Class name of the JDBC driver to be loaded. | Optional: JDBC driver will attempt to be loaded based on the URL specified. |
| Row Limit | rowLimit | Max number of rows to be processed in a source table. | Optional |
| Data Types | dataTypes | List of possible data types to include in search: [ varchar, char, blob, numeric, integer, float, date, time, timestamp, real, longvarchar, longvarbinary, longnvarchar, binary, varbinary, clob, nclob, sqlxml, nvarchar, nchar, tinyint, smallint, bigint, double, decimal, time_with_timezone, timestamp_with_timezone, struct, ref, array, bit, rowid, ref_cursor, other, , java_object, distinct, datalink, boolean ] | Optional |
RDB Mask Configs
| Key Name | Description | Optional or Required | |
| Schema | schemaName | The name of the schema. | Required |
| URL | url | URL for JDBC connection. | Required |
| User | username | The username. | Optional |
| Password | password | The password. | Optional: if authenticating password is required. |
| Driver Configurations | driverConfigs | Additional JDBC driver options | Optional |
| Driver Class | driverClassName | Class name of the JDBC driver to be loaded. | Optional: JDBC driver will attempt to be loaded based on the URL specified. |
| Disable Foreign Keys | disableForeignKeys | Attempt to automatically disable foreign keys in target tables when masking. 1 | Optional |
DarkShield-RDB API Endpoints
The RDB API is an extension of the Files API, which is an extension of the DarkShield base API. As such the RDB API requires not only RDB Search/Mask Contexts, but File Search/Mask Contexts and base API Search/Mask Contexts to be created via their respective endpoints.
A breakdown of API endpoint calls is as follows:
- Search Job
- /api/darkshield/searchContext.create
- /api/darkshield/files/fileSearchContext.create
- /api/darkshield/rdb/rdbSearchContext.create
- /api/darkshield/rdb/rdbSearchContext.search
- /api/darkshield/rdb/rdbSearchContext.destroy
- /api/darkshield/files/fileSearchContext.destroy
- /api/darkshield/searchContext.destroy
- Mask Job
- /api/darkshield/maskContext.create
- /api/darkshield/files/fileMaskContext.create
- /api/darkshield/rdb/rdbMaskContext.create
- /api/darkshield/rdb/rdbMaskContext.mask
- /api/darkshield/rdb/rdbMaskContext.destroy
- /api/darkshield/files/filesMaskContext.destroy
- /api/darkshield/maskContext.destroy
- Search and Mask Job
- /api/darkshield/searchContext.create
- /api/darkshield/maskContext.create
- /api/darkshield/files/fileSearchContext.create
- /api/darkshield/files/fileMaskContext.create
- /api/darkshield/rdb/rdbSearchContext.create
- /api/darkshield/rdb/rdbMaskContext.create
- /api/darkshield/rdb/rdbSearchContext.mask
- /api/darkshield/rdb/rdbSearchContext.destroy
- /api/darkshield/rdb/rdbMaskContext.destroy
- /api/darkshield/files/fileSearchContext.destroy
- /api/darkshield/files/filesMaskContext.destroy
- /api/darkshield/searchContext.destroy
- /api/darkshield/maskContext.destroy
Search/Mask Contexts and File Search/Mask Contexts Example
Below are examples of requests made to generate Search/Mask Contexts and File Search/Mask Contexts, using Postman to display the body of the POST request.
Search Context
File Search Context
Mask Context
File Mask Context
RDB Search/Mask Context Example
RDB Search Context
RDB Mask Context
RDB Search and Mask Operation
Performing search and mask operations using Search Contexts and Mask Contexts previously created.
Table DARKSHIELD from IRI schema containing various PII and binary inside the PDF column.
Binary in PDF column converted to PDF with unprotected PII.
Table DARKSHIELD from MASKED schema containing various PII and binary inside the PDF column.
Binary in PDF column converted to PDF with PII protected.
DarkShield RDB Benchmarks:
If you would like help using this API to scan and/or mask data in your relational database – or with any other data source(s), please contact your IRI representative or email darkshield@iri.com.
