SecurDPS Enterprise SmartAPI for

Java

Release 5.6.1
May 26, 2023

[Link]
Trademark Acknowledgements

Hewlett Packard Enterprise, HPE, NonStop and other trademarks used by Hewlett Packard Enterprise
(“HPE”) are registered trademarks of Hewlett Packard Enterprise Development LP and/or its affiliates.
Microsoft, Windows and .NET are trademarks or registered trademarks of Microsoft Corporation in the United
States and other countries.
JAVA is a registered trademark of the Oracle Corporation in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a Unix-like
operating system, licensed under the free GPL license.
IBM, the IBM logo, and [Link] are trademarks or registered trademarks of International Business Machines
Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of
IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and Trademark
information ([Link]/legal/[Link]).
All other trademarks and registered trademarks are acknowledged and are the property of their respective compa-
nies.

This document was produced by:

comforte AG
Abraham-Lincoln-Str. 22
65189 Wiesbaden
Germany

[Link]

Copyright © 2023 comforte AG. All rights reserved.

This document is the property of comforte AG and the information contained herein is confidential. This
document, either in whole or in part, must not be reproduced or used for purposes other than that for which it has
been supplied, without prior written permission or, if any part hereof is furnished by virtue of a contract with a
third party, as expressly authorized under that contract.
 CONTENTS

1 DISCLAIMER AND IMPORTANT NOTICE! 1

2 Preface 2
2.1 Who Should Read This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 Related Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Introduction to SecurDPS 3
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2 Core Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2.1 Secure High Performance Tokenization / Format Preserving Protection . . . . . . . . . . 3
3.2.2 Application Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2.3 Analysis and Audit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2.4 Designed for IaC and CARTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 High Level Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3.1 Protection Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
[Link] Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
[Link] Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
[Link] Protection Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
[Link] Audit Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3.2 Application Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
[Link] Integration Using the SmartAPI . . . . . . . . . . . . . . . . . . . . . . . . . . 8
[Link] Transparent Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
[Link] Samples for Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3.3 Special Protection Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4 Deployment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4.1 Deployment Options Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4.2 Kubernetes Deployment via Helm Chart . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4.3 Self-Managed Deployment Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
[Link] Option 1: MC/AC On-Premises and Hybrid PN Cluster Deployment . . . . . . 12
[Link] Option 2: Cloud Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 Usage of the SecurDPS Enterprise SmartAPI for Java 14

4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3 Package Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

i
 4.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.6 z/OS Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.7.1 Common SecurDPS Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.8 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 SDF Reference 21
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 CSDF Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.3 Configuration File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4.1 monospaced font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4.2 < > (greater-than and less-than signs) . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4.3 | (vertical bar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4.4 ... (ellipsis) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.5 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6 Configuration of Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6.1 Is Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6.2 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6.3 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
[Link] type: demo | ssh | uds . . . . . . . . . . . . . . . . . . . . . . . . 26
[Link] provider: DEMO | SDREDIS . . . . . . . . . . . . . . . . . . . . . . . 27
[Link] nodes: [<IP or DNS names of PN>, ...] | [<UDS file
location of local PN>,...] . . . . . . . . . . . . . . . . . . . . . . 27
[Link] port: <SSH port address of PNs> . . . . . . . . . . . . . . . . . 28
[Link] user: <ssh user name> . . . . . . . . . . . . . . . . . . . . . . . . . 28
[Link] ssh_keyfile_passphrase_value: [deprecated] <private
key password> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
[Link] ssh_keyfile_passphrase_file: <file containing
private key password> . . . . . . . . . . . . . . . . . . . . . . . . . . 29
[Link] ssh_keyfile: [deprecated] <private keyfile location> 29
[Link] ssh_knownhosts: <public server keys file location> . . 29
[Link] ssh_store_hostkey: true | false . . . . . . . . . . . . . . . . . 30
[Link] ssh_allowed_auth_mechs: <ssh-auth-mechs> . . . . . . . . . . 30
[Link] ssh_keepaliveinterval: <0...99> | 0 . . . . . . . . . . . . . . 31
[Link] client_uds_filename: <client UDS file location> . . . . 31
[Link] min_connections: <0...99> . . . . . . . . . . . . . . . . . . . . . . 31
[Link] max_connections: <0...99> . . . . . . . . . . . . . . . . . . . . . . 32
[Link] node_response_timeout: <0...INT_MAX> . . . . . . . . . . . . . 32
[Link] node_connect_timeout: <0...INT_MAX> . . . . . . . . . . . . . . 33
[Link] cluster_response_timeout: <0...INT_MAX> . . . . . . . . . . . 33
[Link] cluster_connect_timeout: <0...INT_MAX> . . . . . . . . . . . 33
5.6.4 Configuration of gssapi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[Link] user_in_UPN: <user> . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[Link] host_in_SPN: <host> . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
[Link] delegate_creds: <true | false> . . . . . . . . . . . . . . . . . . 34
5.6.5 Configuration of kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

ii
 [Link] config_file: <[Link] file> . . . . . . . . . . . . . . . . . . . 35
5.6.6 Configuration of ssh_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
[Link] method: SECRET_PROVIDER | KEY_FILE . . . . . . . . . . . . . . . 35
[Link] Configuration of secret_provider . . . . . . . . . . . . . . . . . . . . . . 36
[Link] Configuration of key_file . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.7 Configuration of Secret-Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.7.1 Is Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.7.2 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.7.3 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
[Link] <secret provider name> . . . . . . . . . . . . . . . . . . . . . . . . . 39
[Link] type: CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
[Link] Configuration of custom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

6 Appendix 41
6.1 Usage of the StringEncrypter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.2 Using SSH Public Key based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.2.2 Generate Key Pairs with the KeyGen Tool . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.2.3 Using the Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.3 Using Enterprise Identity Access Management based Authentication . . . . . . . . . . . . . . . . 44
6.4 Considerations for using Kerberos with Java Components . . . . . . . . . . . . . . . . . . . . . 44
6.4.1 Considerations for Using Kerberos with Java Components on Windows . . . . . . . . . 44
6.4.2 Considerations for Using Kerberos with Java Components on Linux . . . . . . . . . . . 45

iii
 CHAPTER

ONE

DISCLAIMER AND IMPORTANT NOTICE!

SecurDPS Enterprise is software utilizing advanced encryption and tokenization techniques for protecting
data with encryption keys and/or tokenization secrets known only to you and no one else. In order to reveal
protected data you will need the encryption key(s) and/or tokenization secrets used for protecting the data!

You will assume the entire responsibility at all times for the supervision, management, control and confi-
dentiality of any security data including, but not limited to your encryption key(s) and tokenization secrets,
and you will assume the entire risk for the fraudulent or unauthorized use of your security related data. You
understand that failure to protect your security data may allow an unauthorized person or entity access to
your sensitive data.

It is very important that you back up the data storage attached to the virtual machine which runs the Man-
agement Console regularly, as that is the place where all configuration data, tokenization secrets and en-
cryption keys are being stored. The SecurDPS Management Console creates one main encrypted container
in the data storage. This encrypted container is protected with the unlock passphrase the user specifies
during setup. Make sure to safely store the passphrase that you use for the Management Console. Losing
or misplacing an encryption key or tokenization secret for a set of data is equivalent to losing the data it-
self. Losing your unlock passphrase for the Management Console is equivalent to losing all your data ever
protected with that cluster. Under no circumstances will it be possible for you or comforte to decipher pro-
tected data and restore information contained therein without possession of the applicable encryption key
or tokenization secret and or unlock passphrase for the Management Console.

Furthermore, please also note that the protection provided by SecurDPS Enterprise increases the complex-
ity in your application environment. Practice your disaster recovery plan before you actually have to rely
on it!

1
 CHAPTER

TWO

PREFACE

2.1 Who Should Read This Guide

This document provides a quickstart documentation for administrators and developers installing and using the
SecurDPS Enterprise SmartAPI for Java.

2.2 Related Reading

For a comprehensive and detailed description of the SecurDPS Enterprise product, please refer to the SecurDPS
Enterprise Protection Cluster reference manual.

2
 CHAPTER

THREE

INTRODUCTION TO SECURDPS

3.1 Overview

The comforte SecurDPS data protection suite is a scalable, fault-tolerant enterprise data-centric security solution
that protects sensitive data with minimal effort and little to no impact on existing applications.

SecurDPS allows organizations to achieve end-to-end data protection, helps with compliance to standards like
GDPR, CCPA, or PCI DSS, as well as significantly reduces the impact and liability of data breaches.

3.2 Core Concepts

This section explains the core concepts of SecurDPS. It outlines how the data-centric protection is performed,
how protection operations can be integrated into Enterprise Applications and how the activities in the Protection
Cluster can be audited and analyzed.

3.2.1 Secure High Performance Tokenization / Format Preserving Protection

comforte’s patented Tokenization and Format Preserving Encryption (FPE) algorithms provides linearly scalable,
high performance format preserving data protection. The comforte protection algorithms are stateless, vaultless
and collision-free. The corresponding tokenization / FPE secrets are generated during initialization of the system.
Once SecurDPS is started, the protection secrets are then loaded completely into the memory of the strongly
isolated SecurDPS cluster nodes. All protection / de-protection operations happen purely in memory and CPU
without any disk IO.

SecurDPS supports the configuration of any number of protection strategies. A strategy controls how a sensitive
data element is protected. Properties of a strategy typically include the protection algorithm and its corresponding
attributes, the token format (e.g. how many leading and trailing characters are left in the clear), a distinguish
method (i.e. how plain values can be distinguished from tokens), and more. Format preserving tokens (i.e. the
output of a tokenization / FPE protection operation) can be generated for literally any sensitive data element. This
includes Credit Card Numbers, Social Security Numbers, as well as other personally identifiable information such
as names or email addresses.

The comforte Format Preserving Protection strategies and algorithms have been vetted by some of the leading
independent cryptologists in the field. comforte’s tokenization algorithm is also one of the reference schemes for
static table driven tokenization in the ANSI X9.119-2 tokenization standard (C.3.3.2).

3
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

3.2.2 Application Integration

Once an organization starts implementing data protection measures, the actual encryption or tokenization of sen-
sitive data is pretty straight forward. The complexity of integrating data protection services into Enterprise Appli-
cations is the real key in determining the time and effort it takes to achieve a fully protected state. This factor has
to be given thorough consideration as it determines the cost and risk associated with any data protection project.

comforte identified this key challenge very early on and has designed its data protection suite to make integration
as easy as possible. SecurDPS comes with sophisticated out-of-the-box integration capabilities enabling imple-
mentation of data protection without any change to the application in an absolute transparent fashion. Project time
is shortened by leveraging the integration capabilities. Service interruptions due to development and deployment
activities can typically be avoided. Additionally, the suite provides a comprehensive SDK that have been designed
and documented with the crucial goals of maximizing developer productivity and ease of use.

3.2.3 Analysis and Audit

SecurDPS has built-in audit and analysis capabilities to help different IT or security stakeholders make the right
decisions. The captured meta data creates a solid audit trail and allows stakeholders to gain real-time insights into
key questions around data protection in the enterprise. Some of the most common and important questions would
include the following:

• What is the status of the data protection system?

• How many unique/distinct data elements are being protected vs. how many data elements are being pro-
tected in total?

• How many sensitive data elements were accessed today? (i.e., how many Social Security Numbers were
accessed today/this week/this month/etc.?)

• Am I seeing any peaks in terms of data access to sensitive data elements? By whom?

• Which application or service? Which data elements?

• Is someone accessing sensitive data elements right now?

• What is the status of the data protection system? Where are the different components running?

• How has my protection system behaved in the past? A historical and current behavior comparison can
indicate unusual system behavior.

• Who logged on to the management console? How often and when?

• What actions have been performed?

Besides providing data & insights to these questions, the visualization & presentation is not limited to what is
provided out-of-the-box by SecurDPS, but can be easily integrated into existing security information and event
management (SIEM) frameworks.

3.2. Core Concepts 4

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

3.2.4 Designed for IaC and CARTA

Two main design goals of SecurDPS Enterprise are to allow for easy deployment and automation following Infras-
tructure as Code (IaC) principles, and to allow for easy integration into modern security approaches like CARTA
(Continuous Adaptive Risk and Trust Assessment).

For this purpose SecurDPS Enterprise provides a Management API allowing to programmatically control various
operations. The need for interactive console access is kept to a minimum, and focusing around tasks that cannot
be achieved over the network (e.g. to recover from an invalid network setting).

3.3 High Level Architecture

3.3.1 Protection Cluster

[Link] Overview

The heart of SecurDPS is the Protection Cluster (PC), a centrally managed, scalable and fault-tolerant distributed
cluster of nodes performing the actual protection operations on behalf of the Enterprise Applications (EAs). The
Protection Cluster delivers virtually unlimited scalability of the core components through a unique architecture:

The main components of the Protection Cluster are the Management Console, the Protection Nodes, and the Audit
Console.

3.3. High Level Architecture 5

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] Management Console

The PC is centrally administered through a Management Console (MC). The MC is a specially hardened software
component/node which securely stores all configuration data, keys and secrets required for the cluster operation.
For the initialization of the PC, the MC loads all required information into the PNs non-persistent memory (RAM).
Therefore, once a PN is powered off, all sensitive data previously loaded from the MC is lost.

For more details on the aspects of security please refer to the section Security Architecture in the SecurDPS
Enterprise Protection Cluster reference manual.

[Link] Protection Nodes

The Protection Cluster (PC) consists of a clustering of multiple distributed software components/nodes operating
as Protection Nodes (PNs). Enterprise applications (EAs) connect to the PC to protect or reveal sensitive data
elements using SecurDPS transparent integrations and/or the SecurDPS API.

Any number of PNs can form a PC, distributed across multiple physical servers, datacenters, cloud availability
zones and regions. Individual (sets of) Protection Nodes can be co-located to enterprise applications in order to
provide optimal performance and minimal latency.

PNs do not store any data on local or network disks and perform all their operations in-memory. Data protection is
performed using one of comforte’s patented, highly efficient, stateless tokenization or FPE algorithms. For more
details see section Secure High Performance Tokenization / Format Preserving Protection.

For more details on the aspects of security please refer to the section Security Architecture in the SecurDPS
Enterprise Protection Cluster reference manual.

comforte has also leveraged its heritage of high availability to engineer true fault tolerance into SecurDPS.

SecurDPS handles any outage of one or even multiple PNs transparently to the applications that are utilizing
protection services. In the unlikely event of a failed PN, processing will automatically switch to other PNs without
any interruption of the service for the application.

Additionally, the SecurDPS Enterprise protection cluster provides automatic Cluster Self Healing capabilities,
ensuring that in the event of a failure of a PN, the remaining PNs will not only take over protection operations on
behalf of it, but will also re-initialize the rebooted PN without any involvement of the MC.

For more details, please refer to the section Cluster Self Healing in the SecurDPS Enterprise Protection Cluster
reference manual. For SecurDPS client side integration components see the respective sections on the topic of
failover in their reference manuals.

[Link] Audit Console

The Audit Console (AC) collects and displays metrics about the usage of protection services by the EA. This could
include the number of distinct sensitive data elements accessed by users in plain text, the number of protection
operations per time interval, the number of failed authentications, etc.

The SecurDPS Audit Console can be run standalone or as a cluster on its own. The SecurDPS Audit Console
consists of multiple sub-components / services as depicted in the following graphic:

3.3. High Level Architecture 6

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

The key components of the Audit Console are:

• Kafka: Kafka is a distributed streaming platform. For the SecurDPS Audit Console it is used as the message
broker and “landing platform” for all information from the protection node cluster.

• Elasticsearch: Elasticsearch provides the data storage and analytics engine for Kibana (Dashboard).

• Logstash: Logstash is a data processing pipeline. For the SecurDPS Audit Console, it is used to ingest data
from Kafka into Elasticsearch.

• Kibana: Kibana provides the visualization, esp. in form of dashboards. By default, Kibana will be started
on port 5601.

• Rsyslog: Rsyslog is a log message forwarder that implements the syslog protocol. For the SecurDPS Audit
Console, it is used to locally redirect the incoming log/audit stream from the PNs and the MC to Kafka. By
default, Rsyslog is started on port 514.

3.3.2 Application Integration

SecurDPS Enterprise offers two main options for enterprise applications to consume its protection services as
depicted in the graphic below. On the one hand, SecurDPS provides a comprehensive and easy to use Software
Development Kit (SDK), which consists of SmartAPIs for various programming languages as well as developer
samples for SmartAPI integration. On the other hand, SecurDPS provides various transparent integration options
which allow for an easy data security integration without any need to change application source code.

3.3. High Level Architecture 7

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

In case of the direct use of the SmartAPI, the application source code is extended to utilize the SmartAPI calls
when protection services are desired, e.g. when sensitive data is to be tokenized before landing in files and
databases. The SmartAPI is described in more detail in the following section, Integration Using the SmartAPI.

In the case of transparent integration, no application changes are needed. Instead, the transparency layers provided
by SecurDPS “inject” the data protection into the application. An underlying SecurDPS processing layer identifies
the sensitive data elements to be protected and uses the SmartAPI to either protect or reveal this data. In some
cases, transparent integration can also be done via utilizing so called User Exits or User Defined Functions (UDFs)
of the respective respective technology.

The various transparent integration options of SecurDPS are explained in more detail in section Transparent
Integration.

The following graphic depicts the various layers of a typical computing stack and shows the various options where
SecurDPS data protection can be integrated:

For further details for API integration, refer to section Integration Using the SmartAPI. For the description of the
transparent integration options, see section Transparent Integration.

[Link] Integration Using the SmartAPI

The SecurDPS SmartAPI provides easy programmatic access for integration of SecurDPS protection services
into existing and new applications. In contrast to typical data protection framework APIs, the SmartAPI not
only provides easy access to data protection services, but also provides built-in mission-critical capabilities, e.g.
automatic failover, load balancing and scaling as depicted in the graphic below.

3.3. High Level Architecture 8

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

In general, the SmartAPI will automatically distribute the workload over all available PNs in the cluster. In case of
a failure of one or more PNs, the automatic failover will switch the traffic to the remaining nodes. If there is need
to scale up, additional PNs can be brought up and will be automatically integrated into the Protection Cluster. All
of this will happen completely transparent to the application using the SmartAPI.

[Link] Transparent Integration

With the help of the transparent integration capabilities of SecurDPS, applications typically do not need to be
modified to integrate a data protection layer. In case of transparent integration, the transparency layer “injects” the
protection capabilities and the underlying data processing layer locates and extracts the sensitive information from
the surrounding structures (e.g. JSON, ISO8583). The sensitive data elements are then passed to the SmartAPI
(c.f. figure in the parent section Transparent Integration).

SecurDPS provides various transparent integration mechanisms (“transparent integrators”) for the different frame-
works and layers of a typical computing stack:

1. SecurDPS Virtual File System (VFS)

The SecurDPS Virtual File System (VFS) provides an additional layer or “view” to the actual underlying
file system. The SecurDPS VFS is mounted like an additional drive (Windows) or a new mount point
(Unix/Linux), and underneath points to a given path in the actual file system. When a path in the SecurDPS
VFS is accessed, the directory and file structure is thus exactly the same as in the underlying actual file
system. However, by accessing the file through the SecurDPS VFS, SecurDPS as the (friendly) “Man-in-the-
Middle” can perform transformations for the data within the files. Those transformations are then typically
protect or reveal operations. Typical use cases for utilizing the SecurDPS VFS are file transfers at
the edge of the company network (e.g. file transfer to business partner) or batch type file operations, e.g.
settlement batch processing in financial institutions. The SecurDPS VFS is supported for sequential I/O on
Windows systems, as well as on Linux/Unix systems that support fuse (Filesystem In User Space).

2. SecurDPS Transparent Database Access Integration

The SecurDPS Enterprise Transparent Integration components for database access provide an easy inte-
gration of SecurDPS data protection services into applications which use either a JDBC, ODBC or OCI

3.3. High Level Architecture 9

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

interface. The integration of SecurDPS protection services into JDBC/ODBC/OCI is completely transpar-
ent, i.e. no access or change to the source code of the respective application is required.

3. SecurDPS Transparent Event Streaming Integration

The SecurDPS Enterprise Transparent Integrations for Kafka provide an easy integration of SecurDPS data
protection services into Apache Kafka and the platforms based upon it (e.g. the Confluent Platform). In
the context of Apache Kafka the relevant points of integration are in particular in Kafka producers and
consumers, Kafka Streams and Kafka Connect. SecurDPS provides transparent integrations for all of these
Apache Kafka interfaces / subsystems.

4. SecurDPS Cloud Access Security Broker (CASB) technology

The SecurDPS CASB technology provides an easy and fully transparent way to integrate the SecurDPS
protection layer for web application use cases. As a result, as-a-Service offerings can be used in a completely
secure way, i.e. without having to expose the actual sensitive data to the provider of the as-a-Service solution
(e.g. Salesforce). Similarly, (homegrown) on-premise or private cloud web applications that need access
to the actual underlying sensitive data can be integrated transparently with the otherwise protected source
repositories of that data in the rest of the enterprise.

5. SecurDPS File/Stream Filter

The SecurDPS File/Stream Filter acts like a Unix style filter program. It reads from a source input stream,
performs the configured data transformation actions (e.g. tokenization/FPE of the sensitive data) and then
writes the modified data to an target output stream. The File/Stream Filter supports a file/stdin as source
input and file/stdout as target output streams. Typical use cases for the File/Stream Filter are streaming
use cases as used in combination with Big Data systems like Hadoop. The SecurDPS SDK e.g. includes
some samples to demonstrate use of the File/Stream Filter with Big Data (related) frameworks like Spark,
Pig, HDFS, etc. The File/Stream filter is purely Java based and can thus run on any operating system that
supports Java.

6. SecurDPS Interpose/Intercept technology

The Interpose/Intercept technology is another way (apart from a virtual file system) of inserting additional
functionality into an application without changing it. Using this technology, SecurDPS can intercept I/O
between the file system and the application and perform transformation operations on the data, e.g. to
tokenize all data going to the file system. The Interpose/Intercept technology in SecurDPS is typically
used for those (operating) systems where virtual file system base technology is not available and where
API integration is not desired or possible. The SecurDPS Interpose/Intercept is e.g. used for transparent
integration on HPE NonStop systems.

7. SecurDPS User Defined Functions and custom Translations or Processors

Various frameworks and database technologies allow to enhance their functionality using User Defined
Functions (UDFs) or custom Translations / Processors of some sort. These predefined ways of integration
allow to insert custom logic into the existing data processing activity. SecurDPS includes various integration
samples using UDFs, e.g. to integrate into Hadoop ecosystem related frameworks such as Hive or HBase,
as well as custom Translations/Processors that can be easily integrated into Apache Kafka.

8. SecurDPS Transparent Integration for MQ

The comforte SecurDPS Enterprise MQ Integration provides an easy integration of SecurDPS data protec-
tion services into IBM MQ.

3.3. High Level Architecture 10

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

9. SecurDPS Protection Proxy

The SecurDPS Enterprise Protection Proxy provides an easy integration of SecurDPS data protection ser-
vices into data exchange between various types of source and destination endpoints, such as TCP/IP, SFTP,
AWS S3 buckets, or a combination thereof.

For more information, please refer to the various SecurDPS clients reference manuals, and, in case of HPE Non-
Stop integration, to the SecurDPS Administrator’s Guide for HPE NonStop.

[Link] Samples for Integration

The SecurDPS SDK includes various samples showing how to integrate SecurDPS Enterprise. Those include both
samples for generic SmartAPI integration into Enterprise Applications as well as specific integration samples for
Big Data (related) frameworks like Hadoop, Spark, Pig, HBase, Kafka etc.

For more information, please refer to the various SecurDPS clients reference manuals.

3.3.3 Special Protection Nodes

SecurDPS provides a specialized Protection Node for use with IBM Mainframes and a specialized PN for HPE
NonStop systems. Each of these specialized PNs run locally on IBM Mainframe and on the HPE NonStop,
respectively, serving local applications.

For more information, please refer to the manual SecurDPS Enterprise for IBM Mainframe and to the SecurDPS
Administrator’s Guide for HPE NonStop.

3.4 Deployment Options

3.4.1 Deployment Options Overview

The Protection Cluster (PC) architecture consisting of Protection Nodes (PNs), Management Console (MC) and
Audit Console (AC) offers an extremely flexible model for deployment, both in regards to where the components
are being deployed as well as to how. As a result, Enterprise Applications (EAs) can easily utilize services
provided by the SecurDPS Protection Cluster independent of their own particular deployment model.

The different entities of SecurDPS can run fully distributed across any environment location, including on-premise,
in the cloud or in a hybrid fashion. In addition, the SecurDPS Protection Cluster can be deployed either in a self-
managed way, or as a Kubernetes based deployment via a corresponding Helm Chart. Subsequent versions of
SecurDPS will even allow to mix the self-managed deployment with the Kubernetes based deployment.

3.4. Deployment Options 11

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

3.4.2 Kubernetes Deployment via Helm Chart

The SecurDPS Protection Cluster can also easily be deployed into Kubernetes environments using the correspond-
ing Helm Chart. The actual installation and management of SecurDPS in this deployment model is thus mainly
performed using corresponding Helm commands, with Kubernetes providing the overall orchestration.

3.4.3 Self-Managed Deployment Model

[Link] Option 1: MC/AC On-Premises and Hybrid PN Cluster Deployment

With this deployment option, the Management Console and the Audit Console are deployed on-premises and they
can either be used in conjunction with a Protection Node cluster deployed on-premises or in the cloud. Even with
a model where Protection Nodes are deployed in the cloud, security relevant information is never stored in the
cloud and only resides in-memory of the Protection Nodes.

3.4. Deployment Options 12

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] Option 2: Cloud Deployment

With this deployment option, the overall SecurDPS Protection Cluster, including Management Console, Protection
Nodes and Audit Console, is deployed on a client’s cloud infrastructure. Enterprise Applications utilizing the
services of the PNs can then run either in a cloud environment or in an on-premise deployment.

3.4. Deployment Options 13

 CHAPTER

FOUR

USAGE OF THE SECURDPS ENTERPRISE SMARTAPI FOR JAVA

4.1 Overview

The comforte SecurDPS Enterprise SmartAPI for Java contains APIs and sample code to easily leverage data
protection provided by SecurDPS Enterprise into existing and new Java applications.

4.2 Prerequisites

Java 8 64-bit or later

Note: Before Java 8 Update 151, the Java Cryptography Extension (JCE) is not enabled per default. In order to
install the JCE Unlimited Strength Jurisdiction Policy files follow the instructions at: [Link]
cdoc4j/wiki/Enabling-Unlimited-Strength-Jurisdiction-Policy

4.3 Package Content

The SecurDPS Enterprise SDK for Java is supplied as a zip file containing:

1. SecurDPS Enterprise SmartAPI Java library (lib/)

To use the SmartAPI in your existing development project, copy the lib folder to your project root and add
it to the build path. This folder also contains a DLL to use with z/OS installations.

2. SecurDPS Enterprise Java Demo Project using the SmartAPI (samples/SecurDPSDemo)

This is a typical Maven project, which can be easily imported into any Java IDE. The code examples are
standalone programs that demonstrate how easily protection services provided by the Protection Nodes can
be consumed with the help of the SmartAPI.

3. SecurDPS Enterprise Java API Documentation (doc/javadoc)

Open the file doc/javadoc/com/[Link] with a web browser as the entry point to the Java API
documentation.

Additionally, make sure to add the javadoc JAR file in lib/ to your project, in order to view the API
documentation from inside the Java development environment.

14
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

4. SecurDPS Enterprise SmartAPI for Java

This reference manual is in pdf file format.

5. [Link] file

History of changes of the various SecurDPS Enterprise SmartAPI for Java versions.

4.4 Quickstart

1. Unpack the zip file into your preferred file system location

2. In a Java IDE, import the Maven project in samples/SecurDPSDemo

4.5 Configuration

The behavior of the SecurDPS Enterprise SmartAPI is configurable and can be controlled by:

• the Client Security Definition File (CSDF), or,

• setting the relevant configuration parameters programmatically in the SmartAPI, or,

• a combination of both of the above.

Please see section SDF Reference for a complete reference to the configuration attributes of a CSDF. Alterna-
tively, refer to SecurDPS Enterprise Java API Documentation for the documentation of how to set the attributes
programmatically via the Config class.

4.6 z/OS Considerations

The SecurDPS Enterprise SmartAPI for Java should be installed to a Unix System Services (OMVS) directory of
your choosing.

If your client application is running on a z/OS system and using the services of a local Protection Cluster, you
must configure your CSDF to specify type uds, and include one or more Unix Domain Socket file names under
the nodes attribute. To enable UDS support within your JVM, you must specify the following parameter on your
java run command:

-D<install-dir>/lib/junixsocket-<version>-[Link]

where:

• <install-dir> is the Unix directory to which you installed SecurDPS Enterprise SmartAPI for Java.

• <version> is the version of SecurDPS Enterprise SmartAPI for Java.

The DLL file provides a JNI implementation that interfaces to Unix Domain Sockets support within z/OS.

4.4. Quickstart 15
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

4.7 Troubleshooting

• Make sure that the Protection Nodes are running and can be reached from the very network where the API
implementation is running. For SSH connections, ensure that the respective SSH port is not blocked

• For SSH connections, make sure that the Protection Nodes allow access for the user configured in the client
API (i.e. that the user configured in the cluster SDF and one of public key, Kerberos User Principal, IAM
group the user is part of is properly configured)

• Make sure that the protection strategies used are configured on the Protection Nodes and that access by the
client application is allowed to that specific set of strategies

• Make sure that the translation strategies used are exactly as defined in the Protection Cluster SDF configu-
ration. Note that the strategy names are case-sensitive.

• The Translator close() method needs to be called to release the connection back to the pool. Otherwise,
there may be a situation, where an idle connection is no longer available and the session pool is blocked.

• Make sure that the Translator get() method fetches the same amount of data as the Translator put()
method sent to the PN for translation, otherwise data may be lost.

• In case of an error, check the log files and increase the log level if necessary to get more diagnostic data.

4.7.1 Common SecurDPS Error Messages

This section lists common error messages that may occur when using the SecurDPS SmartAPI and the corre-
sponding steps to recover from those situations:

• Error Connector could not be initialized! max_connections must be

greater than or equal to min_connections!

This message indicates a configuration error in the client component.

Solution Correct the connector configuration in your client configuration (file) by setting the value for
max_connections to a value greater than the value for min_connections.

• Error The ssh_knownhosts attribute is missing or has an incorrect format

This message indicates a configuration error in the client component.

Solution Correct the connector configuration in your client configuration (file) by setting the value for
ssh_knownhosts to a valid path name.

• Error The nodes attribute is missing or has an incorrect format

This message indicates a configuration error in the client component.

Solution Correct the connector configuration in your client configuration (file) by adding the nodes
list with at least one Protection Node address, like the following example:

connector:
nodes:
- [Link]

4.7. Troubleshooting 16
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

• Error No enum constant [Link].

This message indicates a configuration error in the client component. (Only applies to java based client
components)

Solution In most cases, removing the provider setting from the client configuration completely is the
recommended way of fixing this situation.

• Error The user attribute is missing or has an incorrect format

This message indicates a configuration error in the client component.

Solution Correct the connector configuration in your client configuration (file) by setting the value for
user to one of the (SSH) service user names configured in the cluster’s SDF.

• Error Waiting for an idle connection, currently no connection available

This happens when the number of parallel connections in the client component exceeds
max_connections in the client’s connector configuration

Solution If this happens only occasionally, the client may simply retry its operation at a later time. If, on the
other hand, this happens frequently, the current setting for max_connections of the client component’s
connector configuration needs to get increased.

• Error A connection to the cluster could not be established within the

configured timeout

The Protection Cluster was not able to handle the request within the configured timeout.

There could be a multitude of reasons leading to this error message, such as

– the Protection Cluster is not reachable at all

This can potentially be caused by

* incorrect port / nodes configuration settings in the client configuration.

* firewall settings potentially blocking access to the configured Protection Nodes.

* Protection Cluster is actually not up and running

– SSH authentication problems

This can potentially be caused by

* incorrect user setting

* invalid SSH key configuration

* invalid knownhosts settings

Solution Identify the root cause leading to the error message by checking the client log and apply the
corresponding measures to fix it. If no obvious error messages as described above can be identified for
causing this error situation, the actual timeout settings may be too aggressive and may need to be adjusted.

• Error Error [2] strategy PAN: strategy PAN is not defined in SDF

This message indicates that a protection operation has been requested for the PAN strategy, which is not
defined in the Protection Cluster.

Solution Double-check the strategy name for potential spelling errors.

4.7. Troubleshooting 17
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

• Error Error [48] Security Violation: Operation 'Protect' not permitted

for application 'APPLICATION' with strategy 'PAN'

This message indicates, that the Protection Cluster is associating the current client session with the Ap-
plication APPLICATION, which is not allowed to perform the requested protect operation on the PAN
strategy.

Solution As a first step, double-check that the session is actually requesting the required operation on
the correct strategy. If that’s the case, check with the help of the administrator of the Protection Cluster
configuration, if the client’s endpoint is getting correctly associated with the intended Application
definition in the cluster’s configuration.

If everything else has been checked and performing that operation on that strategy for endpoints of that
application is actually required, the cluster configuration needs to get adjusted to grant the according per-
missions.

• Error Error [48] Security Violation: Operation 'Protect' not permitted

for application '' with strategy 'PAN'

Despite the similarity to the previous error message, the empty Application name '' indicates a somewhat
more specific root cause for not having access to the requested protect operation on the PAN strategy,
namely:

The Protection Cluster has not been able to associate the current client’s session with one of the Applications
as defined in the Protection Cluster’s configuration based on its endpoint characteristics.

Solution Check with the administrator of the Protection Cluster configuration, what requirements need to
be matched in order get associated with the correct Application. Depending on the actual configuration,
parameters that may need to get reviewed are:

– SSH user, that is used for connecting to the Protection Cluster

– Active Directory group memberships of the connecting user

– IP address of the connecting client machine

– JWT contents in an OpenID Connect environment

• Error Strategy and operation must be set first!

An input value has been sent into the session for processing without specifying both the requested operation
and the strategy to be used before.

Solution Configure the session with both the requested operation (protect or reveal) as well as a
strategy name, before posting data to be processed with those settings.

• Error Error [2] strategy ACCNUM: data too short for this strategy

In general, protection strategies may be configured to guarantee protecting a minimum amount of data for
a given input value. If the input is not providing enough data to guarantee the generation of a token that
fulfills the configured requirement, the operation will fail with the respective error message.

Solution Post input values, that are long enough to allow the generation of tokens with at least
min-protected characters. Note that additional preserve settings, that may potentially be active
on the strategy, may force the strategy to keep certain portions of the input value in the clear, which impacts
the overall required input length. For example, an input value that should get protected by a strategy with

4.7. Troubleshooting 18
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

min-protected = 6 and preserve-first = 3 needs to have a length of at least min-protected

+ preserve-first (6+3=9) characters.

• Error Error [2] double protection attempt blocked (data remains

unchanged): original data appears already protected based on
distinguish-method

The input value passed into a protect operation has been identified as being protected already by match-
ing the characteristics of the configured distinguish-method of the underlying strategy.

This may happen by actually accidentally passing in already protected data, but it may also happen by
accidentally passing in clear data into the wrong strategy, which is not able to handle this kind of input (and
the clear data accidentally matches the distinguish criteria of the current strategy).

Solution Double-check that the session is configured with the correct strategy and the input value has not
already been protected with this strategy.

• Error Error [2] vault PAN-VAULT: data contains characters not belonging
to configured alphabet

The input value passed into a protect operation contains characters, that cannot be handled by the under-
lying strategy, as they do not belong to the configured alphabet of that strategy.

Solution Using the current strategy for protecting that input value is not possible.

• Error Error [2] vault PAN-VAULT-MASK-OPT0: REVEAL not supported by this

vault

Strategies may be configured to produce irreversible protected values. Others, like the hashing or
masking strategies, do produce irreversible values by nature.

Solution Values created by irreversible strategies cannot be revealed later on.

• Error Error [2] vault FIRST-NAME-VAULT: std::bad_alloc (SecurDPS Appliance <

v7.4.0) or

Error Error [2] vault FIRST-NAME-VAULT: Invalid padding (SecurDPS Appliance

>=7.4.0)

This error typically happens when attempting to reveal an input value with a strategy configured with
padding enabled, which has originally not been protected by that very same strategy.

Solution Double-check the input value and the requested strategy for correctness

• Error Extracting time failed: invalid data

The given input value is not satisfying the input format, that may be required by certain strategies (such as
time/date protection strategies).

Solution Double-check the required input format as defined for the given strategy in the Protection Cluster
configuration

• Error Error [[Link].parse_error.101] parse error

Validation of a JWT (JSON Web Token) being passed for authorization into a SecurDPS session failed,
because the provided input value could not get parsed as a proper JWT token successfully.

Solution Make sure to pass in an actual Base64 encoded JWT.

4.7. Troubleshooting 19
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

• Error Error invalid token supplied

Validation of a JWT (JSON Web Token) being passed for authorization into a SecurDPS session failed,
because the provided input value could not get validated by any of the trusted JWKS endpoints as configured
in the Protection Cluster.

Solution Make sure to pass in an actual Base64 encoded JWT, that has been issued by one of the trusted
JWKS endpoints as configured in the Protection Cluster.

• Error Error jwt expired

The JWT (JSON Web Token) that was previously passed into the current session has expired. In this state
the Protection Cluster is not trusting the session anymore and is therefore refusing to perform any further
operations, until the JWT gets updated with a new valid one.

Solution Pass in a new valid JWT into the session to re-establish a trust situation again.

4.8 Logging

The default output directory for log files on Windows is C:\ProgramData\comForte\SecurDPS\Logs.

SecurDPS Enterprise SmartAPI for Java uses the log4j2 library for logging purposes. The log level can
be controlled with a configuration file named [Link], an example of which is provided in samples/
SecurDPSDemo/src/test/resources.

The following log levels are supported:

Loglevel Meaning
ALL All messages are sent to output.
TRACE Detailed debug messages.
DEBUG Basic debug messages.
INFO Basic information about program flow and runtime events.
WARN Unexpected runtime situations.
ERROR Runtime errors or similar conditions.
FATAL Most severe errors that causes the application to abort.

Per default, in the SmartAPI for Java the log level is set to ERROR for the log file and FATAL on STDERR.

Note: Too many log messages can slow down your application. Therefore, please do not use any level more
verbose than INFO in a production environment (except temporarily for troubleshooting purposes).

For further information about how to configure logging behavior, e.g. different output targets, please refer to the
log4j2 documentation.

4.8. Logging 20
 CHAPTER

FIVE

SDF REFERENCE

5.1 Overview

Before installing and configuring SecurDPS Enterprise it is necessary to carefully determine all applications and
files that should be secured. The result of this analysis is a complete list of all the files containing sensitive data to
be secured and all the application processes accessing these files. Usually this task is performed with the help of
a SecurDPS expert being onsite at the customer’s premises.

The result of the analysis can then be used to create the required SecurDPS configuration files, which are:

1. SDF (Security Definition File)

The SDF is the main SecurDPS configuration file and is used to configure the overall (set of) protection
cluster(s). It contains the definitions around how various elements are to be protected (“strategies”), which
specific underlying protection secrets are to be used and who can get access to those protection services.

For more details on the SDF, please refer to the SDF Reference section within the SecurDPS Enterprise
Protection Cluster reference manual.

2. SCDDF (Secure Cryptographic Device Definition File)

The SCDDF is used in the SecurDPS Enterprise Protection Cluster to configure the connection and security
parameters to use when utilizing an SCD (HSM - Hardware Security Module) as an additional layer of
protection around the secrets (tokenization secrets, etc) used by SecurDPS.

For details on the SCDDF, refer to the SCDDF Reference section within the SecurDPS Enterprise Protection
Cluster reference manual.

3. CSDF (Client Security Definition File)

The CSDF is the SDF file for clients utilizing the protection services provided by the SecurDPS Enterprise
protection cluster. It mainly contains information about how to connect to the Protection Cluster and which
client specific authentication means and components to use (e.g. specifying the client side SSH private key)

Please refer to the respective SecurDPS SmartAPI or Transparent Integration Client reference manual for
more details on the CSDF.

4. IDF (Intercept Definition File)

When intercept technology is used to transparently integrate into an application, the IDF provides all the
required information to locate the sensitive data in the database/records/data stream and which strategies
to use to protect them. The IDF is used in particular to configure the intercept components on the HPE
NonStop.

21
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

Please refer to the SecurDPS Administrators Guide for HPE NonStop for more details.

To provide the required flexibility for more complex configuration needs, SecurDPS Enterprise uses YAML syntax
for all configuration files. YAML enables complex configuration statements, while still being easy to use and
comprehend.

5.2 CSDF Reference

When installing the SecurDPS Enterprise Integration software on your target system, a CSDF template file named
[Link] is provided, usually in the subfolder /config/ or as part of the samples. The CSDF template needs
to be completed manually to adjust it for your environment.

The CSDF identifies:

• Which data files contain sensitive data and, therefore, should be secured by SecurDPS?

• What is the format of a file and where in the file can sensitive data be found?

• How can the SecurDPS Protection Cluster be accessed?

The number of attributes required and the complexity of the configuration vary greatly, depending on which part
of the SecurDPS Enterprise Integration software you are using. For example, only the connection object needs
to be specified for the SmartAPI. For the File/Stream Filter and SecurDPS Virtual File System, on the other hand,
it is necessary to specify which files are to be analyzed and how SecurDPS performs the data protection with the
individual data types.

5.3 Configuration File Format

The configuration files of SecurDPS Enterprise are called Security Definition Files (SDFs), with the filename
optionally prefixed for identifying special use SDFs (e.g. Client SDF, CSDF). All SDFs use YAML syntax and a
short overview to YAML syntax is given in this section.

For more information about YAML, please consult one of the many resources about YAML in the internet (e.g.
Wikipedia is a good starting point).

1. Case sensitivity

The YAML language is case sensitive. Therefore, keywords must occur as specified in this document.

2. Comments

Each line starting with a # character is treated as a comment line.

Example:

# This line is a comment line

Comments can be included at any place in the configuration file.

3. Lists of descriptions

To provide the required flexibility the configuration file must be able to express more complex facts than
a usual application configuration. Therefore, it needs a powerful syntax. This syntax is described in the
following sections.

5.2. CSDF Reference 22

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

Each item in the list starts with the name of the item followed by a colon and at space character (:) within a
single line. The description of the item follows in the next lines. The description can be either a single item
or a list of items. Indentation indicates a nesting of lists . A description is like a name/value pair, where the
value itself can be a list of descriptions:

1 <name>:
2 <value>

Here is an example how to configure a file:

1 files:
2 PAN-FILE-1:
3 fileset: [pan*.txt]
4 ...

4. Single line lists

If a list consists of several elements, comma separate the items and square brackets begin and end the list.

Example:

fileset: [file1*txt, file2*txt, file3*txt]

Or in another style:

1 fileset:
2 - file1*txt
3 - file2*txt
4 - file3*txt

Note:

• A list may consist of a single element.

• YAML uses whitespace indentation to denote structure. Thus, items on multiline lists must be
aligned correctly. Tab characters are not allowed for indentation.

5.4 Notation Conventions

This list summarizes the notation conventions for documenting the SecurDPS configuration files in this manual.

Note that the notations in this manual illustrate only one possible way of specifying an object in the YAML lan-
guage. Some notation conventions (such as ...) may also be valid YAML language items in certain other contexts
(such as ... indicating the end of a YAML document, which is not needed for the SecurDPS configuration files).

5.4. Notation Conventions 23

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

5.4.1 monospaced font

The configuration file notation is written in a monospaced font within a framed text box.

5.4.2 < > (greater-than and less-than signs)

Greater-than and less-than signs indicate variable items to be supplied by the user.

For example:

<field name>

5.4.3 | (vertical bar)

A vertical bar, optionally in combination with curly brackets at the beginning and end of the items, separates
alternatives in a horizontal list, i.e. mutually exclusive key words.

For example:

type: FIXED | VARIABLE | REGEX | ISO8583

Or, in alternative notation with curly brackets, but with the same meaning:

type: { FIXED | VARIABLE | REGEX | ISO8583 }

5.4.4 ... (ellipsis)

An ellipsis following an item indicates that the item can occur any number of times. This notation is mainly used
for describing collections: For example:

must-be-in: [<value>, ...]

Valid expressions of the notation above include collections with only a single item. For example:

must-be-in: [ 2 ]

An ellipsis, optionally surrounded by square brackets, i.e. [...], in a line by itself indicates that irrelevant lines
have been left out for readability’s sake. For example:

1 VAULT1:
2 ...
3 audit-collector: TOKEN-AUDIT1

5.4. Notation Conventions 24

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

5.5 Naming Conventions

The name of the entities, such as applications should reflect the purpose of the entities (e.g. application)
outside the scope of SecurDPS Enterprise. It is strongly recommended to use only lowercase and uppercase
letters, numbers, and the special characters - (dash) and _ (underscore).

5.6 Configuration of Connector

The connector part of the Client SDF details how the SecurDPS client accesses the Protection Node Cluster
in order to consume data protection services. In most cases, the connections to the Protection Node cluster are
established via the SSH protocol. For the z/OS platform, the connections are established via the Unix Domain
Socket (UDS) protocol.

Note: In a CSDF only one connector definition is allowed.

5.6.1 Is Required

Yes

5.6.2 Notation

The listing below shows the connector parameters in a CSDF YAML file.

1 connector:
2 type: demo | ssh | uds
3 provider: [deprecated] DEMO | SDREDIS
4 nodes: [<IP or DNS names of PN>,...] |
5 [<UDS file location of local PN>,...] |
6 NULL
7 port: <ssh port address of PNs> | 22
8 user: <ssh user name > | NULL
9 ssh_keyfile_passphrase_value: [deprecated] <private key password> | NULL
10 ssh_keyfile_passphrase_file: <file contains private key password> | NULL
11 ssh_keyfile: [deprecated] <private keyfile location> | NULL
12 ssh_knownhosts: <public server keys file location> | NULL
13 ssh_store_hostkey: true | false
14 ssh_allowed_auth_mechs: <ssh-auth-mechs>
15 ssh_keepaliveinterval: <0...99> | 0
16 client_uds_filename: <client UDS file location> | NULL
17 min_connections: <0...99> | 0
18 max_connections: <0...99> | 0
19 node_response_timeout: <time in ms> | 5000
20 node_connect_timeout: <time in ms> | 5000
21 cluster_response_timeout: <time in ms> | 0
22 cluster_connect_timeout: <time in ms> | 60000
(continues on next page)

5.5. Naming Conventions 25

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

(continued from previous page)

23 ssh_key:
24 method: SECRET_PROVIDER | KEY_FILE
25 secret_provider:
26 name: <name of secret provider>
27 secret_id: <secret identifier> | NULL
28 key_file:
29 file: <private keyfile location> | NULL
30 passphrase: <private key password> | NULL
31 gssapi:
32 user_in_UPN: <user> | NULL
33 host_in_SPN: <host> | NULL
34 delegate_creds: true | false
35 kerberos:
36 config_file: <file name of [Link]>

5.6.3 Attributes

[Link] type: demo | ssh | uds

The attribute type defines the connection type. The default value is ssh.

Previous releases of SecurDPS used the provider attribute to specify both the type of provider, with the value
SDREDIS automatically implying that the connection type was ssh. The type attribute now specifies the connec-
tion type, with values ssh and uds automatically implying that the provider will be SDREDIS. New configura-
tions should use the type attribute in preference for the provider attribute. For the z/OS platform, you must specify
type as uds if you want to use a local PN running on the same machine.

The following types are supported:

Value Description
demo Performs the data protection via a simple Caesar cipher (character shifting). It performs
a simple local PROTECT/REVEAL translation process without any connection to an ex-
ternal Protection Provider Engine. This option can be used to check the configuration
or to simply do a quick test without requiring to set up a complete Protection Cluster.
Note: all other attributes are ignored when using demo.
ssh Communicates to the Protection Cluster using the RESP protocol (REdis Serialization
Protocol) over an SSH connection. This option is the default.
uds Communicates to the local Protection Cluster using the RESP protocol (REdis Serial-
ization Protocol) over a Unix Domain Sockets connection. This option only applies to
the z/OS platform. Note: connection pooling is not supported when using uds.

5.6. Configuration of Connector 26

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] provider: DEMO | SDREDIS

The attribute provider defines a specific Provider name. The default value is implied by the value of the type
attribute.

This attribute is deprecated. Please use the type attribute instead.

The following providers are supported:

Value Description
DEMO Performs the data protection via a simple Caesar cipher (character shifting). It performs
a simple local PROTECT/REVEAL translation process without any connection to an ex-
ternal Protection Provider Engine. This option can be used to check the configuration or
to simply do a quick test without requiring to set up a complete Protection Cluster.
SDREDIS Communicates to the Protection Cluster using the RESP protocol (REdis Serialization
Protocol) over either SSH or Unix Domain Sockets.

[Link] nodes: [<IP or DNS names of PN>, ...] | [<UDS file location of local
PN>,...]

When the type attribute is ssh, this attribute specifies the list of IP addresses or DNS names for all Protection
Nodes in a Cluster to which the SecurDPS Enterprise Integration software wants to connect.

When the type attribute is uds, this attribute specifies the list of Unix Domain Socket file locations on which the
local Protection Nodes are listening, and to which the client wishes to connect.

This specification is required for all types except demo.

SSH Example:

1 nodes:
2 - [Link]
3 - [Link]
4 - [Link]

UDS Example:

1 nodes:
2 - /usr/local/securDPS/pn1
3 - /usr/local/securDPS/pn2
4 - /usr/local/securDPS/pn3

5.6. Configuration of Connector 27

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] port: <SSH port address of PNs>

The SSH port number where the cluster of Protection Nodes is listening. The default value is 22.

This specification is only required for type ssh, and if the port differs from the default.

[Link] user: <ssh user name>

SSH application user name, that needs to access a Protection Node for protection purposes.

This attribute only applies if the type attribute is set to ssh.

Note:

The user name can be obfuscated with the help of the StringEncrypter if desired:

java -jar lib/StringEncrypter_v2.[Link] --gui

See more on Usage of the StringEncrypter.

[Link] ssh_keyfile_passphrase_value: [deprecated] <private key password>

Passphrase used to protect the private key of the application user.

This attribute is deprecated. Please use the ssh-key attribute instead. See more on Configuration of ssh_key.

This optional attribute only applies if the type attribute is set to ssh.

See more on Using SSH Public Key based Authentication.

Note:

The passphrase can be obfuscated with the help of the StringEncrypter if desired:

java -jar lib/StringEncrypter_v2.[Link] --gui

See more on Usage of the StringEncrypter.

Alternatively, the passphrase can be read from a file. For that, please use the attribute
ssh_keyfile_passphrase_file.

5.6. Configuration of Connector 28

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] ssh_keyfile_passphrase_file: <file containing private key password>

Reads the private key passphrase from a file. The passphrase is used to protect the private key of the application
user.

This is optional, and only applies if the type attribute is set to ssh.

See more on Using SSH Public Key based Authentication.

Note:

The passphrase can be obfuscated with the help of the StringEncrypter if desired:

java -jar lib/StringEncrypter_v2.[Link] --gui

See more on Usage of the StringEncrypter.

Example:

ssh_keyfile_passphrase_file: c:/[Link]/.ssh/[Link]

Alternatively, the password can be set directly in the CSDF using the attribute
ssh_keyfile_passphrase_value.

[Link] ssh_keyfile: [deprecated] <private keyfile location>

This attribute is used to set location, path, and filename of the private key file of the application user.

This attribute is deprecated. Please use the ssh-key attribute instead. See more on Configuration of ssh_key.

This attribute only applies if the type attribute is set to ssh.

See more on Using SSH Public Key based Authentication.

Example:

ssh_keyfile: C:/user/.ssh/id_rsa.pkk

[Link] ssh_knownhosts: <public server keys file location>

Location of the SSH known_hosts file, which contains the list of known Protection Node Cluster public host
keys used to verify the identity of the remote hosts and thus prevent impersonation or eavesdropping.

This attribute only applies if the type attribute is set to ssh.

Note: Setting the SSH known_hosts file attribute enables strict checking of host keys. The session can be
established only if the host’s public key is in the known_hosts key file.

Ask your SecurDPS Enterprise Protection Cluster administrator for the RSA key to be added to your
known_hosts file for every Protection Node that you have configured with the nodes parameter like:

5.6. Configuration of Connector 29

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

PN-IP-ADDRESS ssh-rsa HOST-KEY

Example:

ssh_knownhosts: C:/user/.ssh/known_hosts

Known host file content:

1 [Link] ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDfg3GyJf3p...

2 [Link] ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDfg3GyJf3p...
3 [Link] ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDfg3GyJf3p...

[Link] ssh_store_hostkey: true | false

Boolean value (true or false) to store the host key in the known_hosts file automatically.

This attribute only applies if the type attribute is set to ssh.

Note: Do not use this parameter for production.

The host key is not overwritten if it has been changed! Ask your SecurDPS Enterprise Protection Cluster admin-
istrator for the Protection Node host key and enter it manually in the known_hosts file.

[Link] ssh_allowed_auth_mechs: <ssh-auth-mechs>

This parameter is used to configure which authentication methods are tried during user authentication. It is a list
of method names delimited by ‘|’.

This attribute only applies if the type attribute is set to ssh.

However, the specific set of mechanisms allowed for user authentication are preset on the SSH server side. There-
fore this parameter can only restrict the available authentication mechanisms as offered by the SSH server. Ac-
cordingly, for the SecurDPS SmartAPI to work, at least one authentication mechanism has to match between client
and server.

The following authentication methods are supported:

Value Description
gssapi-with-mic gssapi-with-mic authentication via SSH.
publickey public key authentication via SSH”
password password authentication via SSH

Note: Please note that restricting the user authentication mechanisms on the client side can lead to problems e.g.
when a required authentication resource becomes unavailable. Restrictions of user authentication mechanisms
should usually be done on the SSH server side. It is not recommended to change this parameter in the SecurDPS
SmartAPI.

5.6. Configuration of Connector 30

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

Example:

ssh_allowed_auth_mechs: "gssapi-with-mic|publickey"

[Link] ssh_keepaliveinterval: <0...99> | 0

This parameter specifies how often (in seconds) to send a periodic keep-alive message to the host. The keep-alive
interval determines if an idle connection is still active. If 5 consecutive keep-alive messages are unanswered the
client will close the connection and automatically attempt to reconnect.

This parameter is ignored when the connection pool is disabled. For more details see min_connections: <0...99>
and max_connections: <0...99>.

The keep-alive interval must be an integer (in seconds). Set the value to 0 to disable. Default is 0. A negative
number is not allowed.

This is optional, and only applies if the type attribute is set to ssh.

Note: This parameter is only available in SecurDPS Enterprise SmartAPI for Java and/or in the SecurDPS
Enterprise Java tools that build on SmartAPI version 5.5.0+.

Example:

ssh_keepaliveinterval: 5

[Link] client_uds_filename: <client UDS file location>

This parameter specifies the Unix Domain Socket file location to which the client will bind. The actual filename
to which the client binds is the client_uds_filename with .client.<unique-number> appended.

If not specified, client_uds_filename defaults to the name of the server’s UDS file location, as configured under
attribute nodes when type is uds.

This attribute only applies if the type attribute is set to uds.

Example:

client_uds_filename: /tmp/SecurDPS/myapp

[Link] min_connections: <0...99>

This parameter defines the number of connections to be created automatically at startup with a minimum pool
size.

The default value is 0. A negative number or a larger number than the value for max_connections is not
allowed.

This is optional, and only applies if the type attribute is set to ssh.

Example:

5.6. Configuration of Connector 31

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

min_connections: 5

[Link] max_connections: <0...99>

The implemented connection pool supports a value for the maximum pool size by max_connections. That means if
all available connections are taken and the current pool size is less than the configured maximum, a new connection
will be created. Otherwise, SecurDPS will wait for an idle connection.

The default value is 0. A negative number or a smaller number as the value for min_connections is not
allowed.

This is optional, and only applies if the type attribute is set to ssh.

Note: The connection pooling is off with a value 0 for max_connections.

Example:

max_connections: 5

[Link] node_response_timeout: <0...INT_MAX>

The node_response_timeout parameter specifies the time in milliseconds which a read operation will wait
for outstanding application level data to be received. If no application level data is outstanding (e.g. if a get() is
called more times than the corresponding put()) then the node_response_timeout will by design not be
honored. Instead, in this case, SecurDPS will wait until the next put() is invoked, which then triggers a reset of
the timeout value to the value of node_response_timeout again.

In case the given node_response_timeout expires, the node is considered unavailable and processing is
continued using any other available node within the same cluster.

The default value is 5000. A timeout less than 0 is not allowed.

Note: The value for node_response_timeout should not be smaller than 2000 ms (2 seconds). If the value
is too small, then the data may not be sent over the network to a protection node, being processed, and sent back
within the small time window, and thus the node may appear to be unresponsive.

Example:

node_response_timeout: 2000 # 2 seconds

5.6. Configuration of Connector 32

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

[Link] node_connect_timeout: <0...INT_MAX>

The node_connect_timeout parameter specifies the time in milliseconds within which a connection to a
Protection Node should be successfully established.

In case the given node_connect_timeout expires, the node is considered unavailable and a connection to
another node is initiated.

The default value is 5000.

Example:

node_connect_timeout: 10000 # 10 seconds

[Link] cluster_response_timeout: <0...INT_MAX>

The cluster_response_timeout parameter specifies the time in milliseconds within which processed data
should be successfully retrieved from the Protection Cluster, i.e., from any of the available Protection Nodes.

In case the given cluster_response_timeout expires, the cluster is considered unavailable and a failure
is reported.

The default value is infinite.

Example:

cluster_response_timeout: 600000 # 10 minutes

[Link] cluster_connect_timeout: <0...INT_MAX>

The cluster_connect_timeout parameter specifies the time in milliseconds within which a connection to
a Protection Cluster should be successfully established.

In case the given cluster_connect_timeout expires, the cluster is considered unavailable and a failure is
reported if the application is trying to create a new connection to the Protection Cluster, e.g., the application tried
to create a new translator instance.

If the timeout expires during an already running data processing, i.e., the application successfully created a trans-
lator instance and started to process the data, then the timeout does not take effect.

The default value is 60000 (1 minute).

Example:

cluster_connect_timeout: 120000 # 2 minutes

5.6. Configuration of Connector 33

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

5.6.4 Configuration of gssapi

[Link] user_in_UPN: <user>

This optional parameter is used to specify a custom user name to use in the User Principal Name (UPN) for the
GSSAPI/Kerberos based authentication.

Set only if instructed to do so by comforte or if you are very familiar with GSSAPI/Kerberos.

Example:

1 connector:
2 [...]
3 gssapi:
4 user_in_UPN: my-other-user
5 [...]
6 [...]

[Link] host_in_SPN: <host>

This optional parameter is used to specify a custom host name to use in the Service Principal Name (SPN) for the
GSSAPI/Kerberos based authentication.

Set only if instructed to do so by comforte or if you are very familiar with GSSAPI/Kerberos.

Example:

1 connector:
2 [...]
3 gssapi:
4 host_in_SPN: the-actual-hostname-part-in-the-SPN
5 [...]
6 [...]

[Link] delegate_creds: <true | false>

This optional parameter is used to set whether the client credentials, i.e. the Kerberos TGT, is delegated to the
SecurDPS Protection Cluster for impersonation purposes.

Default value is false.

Set only if instructed by comforte to do so or if you are very familiar with GSSAPI/Kerberos.

Example:

1 connector:
2 [...]
3 gssapi:
4 delegate_creds: true
5 [...]
6 [...]

5.6. Configuration of Connector 34

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

5.6.5 Configuration of kerberos

[Link] config_file: <[Link] file>

This parameter is only required if Using Enterprise Identity Access Management based Authentication. It specifies
the path of the client side Kerberos configuration file to use, typically referred to as [Link]. The actual file
content follows the layout and content of the MIT Kerberos [Link].

This parameter is only required for SecurDPS Java components, or, in case a custom, non-default [Link] file
is to be used with non-Java SecurDPS components on Linux systems (where the default is /etc/[Link]).

Not applicable for .NET components.

A sample [Link] is included in the SecurDPS installation (which needs to be adjusted for each specific
IAM environment) and could look as follows:

1 [libdefaults]
2 forwardable = true
3 default_realm = [Link]
4

5 [realms]
6 [Link] = {
7 kdc = [Link]
8 admin_server = [Link]
9 }
10

11 [domain_realm]
12 [Link] = [Link]
13 .[Link] = [Link]

The correct configuration of the [Link] can be complex as a result of complexity in the Enterprise IAM
environment. Therefore setting up the [Link] to be used will typically be done together with a comforte
expert.

5.6.6 Configuration of ssh_key

If the type attribute is set to ssh, then this section is used to specify how the SSH private key is loaded and from
where it is obtained.

[Link] method: SECRET_PROVIDER | KEY_FILE

If specifying SECRET_PROVIDER, then also a subsection secret_provider must be provided which is then
used to set further details of the secret provider.

If specifying KEY_FILE, then the location of the SSH private key and the optional passphrase value must be
specified in subsection key_file.

The default value is KEY_FILE.

Example:

5.6. Configuration of Connector 35

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

1 connector:
2 [...]
3 ssh_key:
4 method: SECRET_PROVIDER
5 secret_provider:
6 name: [...]
7 secret_id: [...]
8 [...]

Example:

1 connector:
2 [...]
3 ssh_key:
4 method: KEY_FILE
5 key_file:
6 file: [...]
7 passphrase: [...]
8 [...]

[Link] Configuration of secret_provider

This section is used to specify the secret provider to be used for selecting and obtaining the SSH private key.

name: <name of secret provider>

This attribute is used to reference a secret provider configuration found in section secret_providers.

There is no default value for this attribute.

Example:

1 secret_providers:
2 SAMPLE-CUSTOM-PROVIDER:
3 [...]
4

5 connector:
6 [...]
7 ssh_key:
8 method: SECRET_PROVIDER
9 secret_provider:
10 name: SAMPLE-CUSTOM-PROVIDER
11 secret_id: NULL
12 [...]

For further details about section secret_providers see Configuration of Secret-Providers.

5.6. Configuration of Connector 36

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

secret_id: <secret identifier>

If there are multiple different secrets (i.e. SSH keys) which can be obtained from a secret provider, then this
optional attribute is used to specify the secret of interest. Whether or not a secret identifier needs to be specified
here is determined by the actual secret provider in use.

The default value of this attribute is NULL.

[Link] Configuration of key_file

This section is used to specify the location and other information related to the SSH private key file to be used for
SSH authentication.

file: <private keyfile location>

This attribute is used to set location, path, and filename of the private key file of the application user.

See more on Using SSH Public Key based Authentication.

Example:

key_file: C:/user/.ssh/id_rsa.pkk

passphrase: <private key password>

Passphrase used to protect the private key of the application user.

This is optional, and only applies if the type attribute is set to ssh.

See more on Using SSH Public Key based Authentication.

Note:

The passphrase can be obfuscated with the help of the StringEncrypter if desired:

java -jar lib/StringEncrypter_v2.[Link] --gui

See more on Usage of the StringEncrypter.

5.7 Configuration of Secret-Providers

The secret_providers part of the Client SDF is used to configure one or more secret providers to be refer-
enced and used in other parts of the SDF.

A secret provider is a service hosting and providing secrets at runtime. In this context a secret may be an SSH
private key needed by a SecurDPS client component when establishing an SSH session with a SecurDPS Protection
Node.

5.7. Configuration of Secret-Providers 37

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

Currently (i.e. subject to change in future versions) only a custom type of secret provider is supported. This is a
secret provider implemented by the user outside the scope of SecurDPS but provided and assigned at runtime as a
JAR file.

The JAR file implementing the custom secret provider must be accessible to the SecurDPS client tools. It is
recommended to set the full file path of the archive file using the attribute secret_provider_jar.

The custom type secret provider hides all the details of obtaining the secret at runtime but must implement the
interface [Link]:

1 public interface SecretProvider {

2

3 String loadSecret(final String secret_id) throws IOException;

4

5 void setProperties(Map<String, String> properties)

6 throws IllegalArgumentException;
7 }

loadSecret(final String secret_id)

A public method that is invoked by the SecurDPS client component in order to obtain the secret identified by
secret_id from the secret provider.

The secret_id in this case is specified in other parts of the client SDF (e.g. Configuration of Connector) where
the actual secret provider is referenced.

void setProperties(Map<String, String> properties)

A public method invoked by the SecurDPS client component used to forward an optional map of property
name/value pairs from the secret_providers entity to the secret provider.

5.7.1 Is Required

No

5.7.2 Notation

The listing below shows the secret_providers section in a CSDF YAML file.

1 secret_providers:
2 <secret provider name>:
3 type: CUSTOM
4 custom:
5 secret_provider_class: <name of implementing class>
6 secret_provider_jar: <path name of jar file implementing the secret
˓→ provider>
7 properties:
8 <property name 1>: <property value 1>
(continues on next page)

5.7. Configuration of Secret-Providers 38

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

(continued from previous page)

9 <property name 2>: <property value 2>
10 ...
11 <property name n>: <property value n>

5.7.3 Attributes

[Link] <secret provider name>

A freely selectable but unique name of the secret provider.

The name should be in uppercase and start with a letter. It may may contain letters, digits and the special characters
- and _.

This attribute is required.

[Link] type: CUSTOM

This attribute is used to specify the type of the secret provider. Currently only the type CUSTOM is supported.

The default value of this attribute is CUSTOM.

[Link] Configuration of custom

This section is used to configure a secret provider of type CUSTOM. A custom type secret provider is implemented
and provided by the user outside the scope of the SecurDPS client component which makes use of it. It is made
available to the SecurDPS client component as an external JAR file.

secret_provider_class: <name of implementing class>

This attribute is set with the full qualified name (i.e. including package names) of the custom secret provider
implementation.

There is no default value for this attribute.

secret_provider_jar: <path name of jar file implementing the secret

provider>

This attribute is used to set location, path, and filename of the jar archive path name of jar file implementing the
custom secret provider.

There is no default value for this attribute.

Example:

secret_provider_jar: C:/projects/libs/[Link]

5.7. Configuration of Secret-Providers 39

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

properties

The optional properties section is used to specify property name and value pairs potentially needed by the
secret provider implementation at runtime.

It therefore depends on the implementation of the secret provider whether properties are required at all and what
name/value pairs are to be specified.

There is no default value for this attribute.

5.7. Configuration of Secret-Providers 40

 CHAPTER

SIX

APPENDIX

6.1 Usage of the StringEncrypter

Passwords should not be stored as plain text in configuration files such as the CSDF. However, by design, at some
point any cryptographic service that is to be started without any user interaction, requires to have access to the
actual plain password/passphrase to be able to unlock the associated encrypted files (e.g. the SSH private key).

To address this issue as good as per design of the problem possible, SecurDPS includes the capability to obfuscate
sensitive strings in configuration files with its StringEncrypter component.

Danger: The StringEncrypter only provides a level of obfuscation to a sensitive pass-

word/passphrase. It does not provide strong encryption for any purposes! Do not use for any
other purpose than described herein and also be aware of its limitations by design of the problem
it addresses!

The SecurDPS StringEncrypter can be used as follows:

1. Open a command prompt, change into the directory where the SecurDPS StringEncrypter is installed

2. On Windows, run [Link] to start the StringEncrypter GUI:

[Link]

For the operating system independent alternative, enter the following java command from the SecurDPS
install directory:

java -jar lib/StringEncrypter_v2.[Link] --gui

3. Enter your sensitive data in the Plain Text field.

41
 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

4. Click the Encrypt button or press the Enter key on your keyboard to copy the encrypted text to the
clipboard.

5. Paste encrypted text into your CSDF configuration file or into your private key passphrase file.

6. Close StringEncrypter by clicking on the Leave button or pressing the ESC key on Linux.

6.2 Using SSH Public Key based Authentication

6.2.1 Overview

The SSH Client used in the File/Stream Filter and the SecurDPS Virtual File System program supports public-key
authentication with a public-private key pair. This means that the public key is placed on the SSH server and the
private key is placed on your local workstation where the File/Stream Filter or the SecurDPS Virtual File System
program is running.

The required format of the private key file is PEM OpenSSH format for RSA or DAS key type. A private key in
PEM OpenSSH format starts with:

-----BEGIN DSA PRIVATE KEY-----

or

-----BEGIN RSA PRIVATE KEY-----

and ends with the following tag:

-----END DSA PRIVATE KEY-----

or

-----END RSA PRIVATE KEY-----

A public-private key pair can be generated in various ways. The SecurDPS Enterprise Integration Suite contains a
SSH KeyGen tool that can be used to generate key pairs for secure SSH authentication. Other Tools like PuTTYgen
or the usual OpenSSH ssh-keygen can be used to generate these keys in PEM format.

6.2.2 Generate Key Pairs with the KeyGen Tool

To generate a SSH publickey/private key pair with the help of the SecurDPS SSH KeyGen tool, please follow
these steps:

1. Launch the KeyGen dialog:

C:\Program Files\comForte\SecurDPS\SDFS\[Link]

Alternatively, open a command prompt, go to the directory where SecurDPS is installed, and enter the
following Java command:

6.2. Using SSH Public Key based Authentication 42

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

java -jar lib/SSHKeyGen_v1.[Link] --gui

2. In the dialog, fill in the input fields:

(a) Add a comment, e.g. your email address and/or key type and size (optional),

(b) Enter a unique key passphrase in the Passphrase and Confirm Passphrase fields (optional),

(c) Choose a location where the generated key files should be stored or use the default value,

3. Click the Generate Key button to generate the private and public key pair and to save the newly gener-
ated keys into a private and a public key file as it is shown in field File Location,

4. Click on Copy to copy the public key in YAML multiline format to paste it into the SDF of the SecurDPS
Protection Cluster.

6.2.3 Using the Key Pair

A generated public-private key pair is used in the following way:

1. Update the CSDF configuration:

(a) Open your CSDF configuration file in a YAML editor of your choice.

(b) Set the path + filename (it can be relative) as value for the ssh_keyfile parameter in your
connector section in your CSDF (see example below).

(c) Set the private key password as value for the ssh_keyfile_passphrase_value if you have the
private key encrypted; use the StringEncrypter to obfuscate the password.

(d) Save the modified CSDF configuration file.

6.2. Using SSH Public Key based Authentication 43

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

2. Send the public key to your SecurDPS Protection Cluster administrator for updating the Protection Node
SDF configuration.

6.3 Using Enterprise Identity Access Management based Authen-

tication

SecurDPS can be integrated into the corporate Kerberos and LDAP (e.g. MS Active Directory), and/or OpenID
Connect (OIDC) based Identity and Access Management (IAM) system.

For a comprehensive overview of how the Enterprise Identity and Access Management Integration with SecurDPS
can be used, please refer to the SecurDPS Enterprise Protection Cluster reference manual.

In the case of Kerberos/LDAP based IAM Integration, note for the SecurDPS Enterprise Integration components
that

• .NET based components as well as the Linux components typically do not require any additional setup steps.

• Java based components require to create and reference a Kerberos configuration file

As the initial setup for IAM integration, both in case of Kerberos/LDAP or OIDC, touches various entities and
groups within the Enterprise, typically a comforte expert will help and guide through the process.

6.4 Considerations for using Kerberos with Java Components

6.4.1 Considerations for Using Kerberos with Java Components on Windows

Important: Kerberos Authentication with Windows and SecurDPS Java components will not work
unless the Windows Registry key described below is set correctly!

To use Kerberos authentication with SecurDPS on the Microsoft Windows Operating System, the key
allowtgtsessionkey has to be set in the Windows Registry.

Note that this requirement is not SecurDPS specific but a general requirement for accessing the Windows native
ticket cache through Java. The Registry key allowtgtsessionkey allows accessing the session key from the
initial Kerberos ticket (TGT - Ticket Granting Ticket) obtained during the login of the user to the workstation.
This session key is required to encrypt further communication with the Key Distribution Center (KDC).

The Registry key itself has to have the following properties:

• Value Name: allowtgtsessionkey

• Value Type: REG_DWORD

• Value: 0x00000001 (1)

The allowtgtsessionkey Registry key has to be added to a specific path in the Windows Registry:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\
˓→Parameters

6.3. Using Enterprise Identity Access Management based Authentication 44

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

Important: After inserting the key make sure that its value is really shown as hexadecimal
0x00000001 or decimal 1 respectively.

Note that going forward, Microsoft’s plan is to disable the access via this mechanism completely in subsequent
Windows versions. Currently only if the Credential Guard is enabled in Windows 10, the access to the session key
is not possible at all anymore, even with the allowtgtsessionkey registry key set.

Unfortunately Microsoft did not coordinate those breaking changes with Oracle, and so a different approach that
does not require the registry key to be set anymore will only be available with Java 13 and later (release September
2019). See corresponding Java Enhancement Proposal.

6.4.2 Considerations for Using Kerberos with Java Components on Linux

To use Kerberos with SecurDPS Java components on Linux, it has to be ensured that the Kerberos installation on
the Linux machine is configured to use a FILE based credential cache as opposed to a KEYRING based credential
cache. The reason is that Java currently exclusively supports FILE based credential caches.

To validate that the Kerberos configuration does not use a KEYRING based configuration, please check your
[Link] file for not having a line similar to the following included:

default_ccache_name = KEYRING:persistent:%{uid}

The above line configures Kerberos to actually use a KEYRING based credential cache as opposed to a FILE based
one. As the MIT Kerberos default is to use a FILE based credential cache if not specified explicitly otherwise, it
is typically sufficient to comment out the line default_ccache_name and then do a kinit again.

Note that the credential cache used will also be shown in the output of a klist command:

• Output with KEYRING based cache (will not work):

1 [[Link]@laptop-jd ~]$ klist

2 Ticket cache: KEYRING:persistent:1000:krb_ccache_J3Hr9DW
3 Default principal: testuser1@[Link]
4

5 Valid starting Expires Service principal

6 03/02/2019 04:47:11 03/02/2019 14:47:11 krbtgt/[Link]@CFDEV.
˓→LOCAL
7 renew until 03/09/2019 04:47:00
8 [[Link]@laptop-jd ~]$

• Output if using a FILE based cache (will work):

1 [[Link]@laptop-jd ~]$ klist

2 Ticket cache: FILE:/tmp/krb5cc_1000
3 Default principal: testuser1@[Link]
4

5 Valid starting Expires Service principal

6 03/02/2019 04:56:46 03/02/2019 14:56:46 krbtgt/[Link]@CFDEV.
˓→LOCAL
(continues on next page)

6.4. Considerations for using Kerberos with Java Components 45

 SecurDPS Enterprise SmartAPI for Java, Release 5.6.1

(continued from previous page)

7 renew until 03/09/2019 04:56:43
8 [[Link]@laptop-jd ~]$

6.4. Considerations for using Kerberos with Java Components 46