Keystore Management

This section describes how DirX Access uses cryptography. It is intended to provide DirX Access administrators with insight into the cryptography-dependent mechanisms and to enable them to verify the overall security of their specific deployment. The goal of this presentation is to provide a fast and easy way to get answers to cryptography questions, whether from the perspective of each particular keystore or a specific feature.

Security Architecture

This section describes the DirX Access security architecture and its operation within DirX Access. The overall architecture of DirX Access can be divided into three layers.

A persistence layer is represented by the Application and User Repositories providing data to a layer of Services containers. The Services containers communicate with internal client components such as the PEPs, and so on.

The concept behind the layered architecture is simple: to enable the application of different security measures on different layers; specifically, to deploy the server layer in a secure intranet environment and the clients part in the demilitarized zone (DMZ).

The next sections describe the security specifics of the environments in which the DirX Access system components operate along with the recommended measures to apply.

Application Repository

The Application Repository must be deployed in a highly-protected environment solely under the control of the administrator. We recommend limiting the access to the machine just to the ports that communicate with the Services containers.

What can a breach mean?

Altering configuration data - an attacker is able to influence a run-time system functionality (for example, authentication and authorization policies).
Cryptomaterial theft - an attacker is able to retrieve the cryptographic keys and leverage them.
Private data theft - in specific use cases, the Application Repository may contain users’ private data. As a result, the configuration must enable the use of risk-based authentication, FIDO authentication, or OTP authentication.
User impersonation - the OTP data stored in the Application Repository might be leveraged by an attacker to impersonate a corresponding system user for the validity interval of the OTP data.

What doesn’t a breach mean?

Getting into a User repository - the Application Repository does not contain any credentials for the User Repository.
Stealing FIDO private credentials – a theft of FIDO credentials from the Application Repository does not lead to any possibility of impersonation of any user by an attacker.

User Repository

The User Repository is a component to be deployed in a highly-protected environment solely under the control of the administrator. We recommend limiting the access to the machine just to the ports communicating with the Services containers. The User Repository serves to DirX Access only as a source of user information and is not managed by it (contrary to the Application Repository). Hence, from the perspective of DirX Access, we cannot really predict what is contained within it. Typically, however, a breach means a private data and credentials theft.

Services Container

The Services container is a component to be deployed in a highly-protected environment solely under the control of the administrator. We recommend limiting the access to the machine just to the ports communicating with the internal clients and repositories. This configuration may, however, mean that the standard HTTP(S) ports are open; in this case, an additional protection can be applied by limiting the access to the ports on the intranet.

In some use cases, the ports must be accessible to third-party clients residing outside the intranet (for example, via SOAP and RESTful WebServices). Note that DirX Access ensures protection against malicious content of the communication (for example, protection against malicious code injection). However, external means should be used to protect the connection itself against attacks (for example, DoS).

What can a breach mean?

Repository credentials theft - the instance file system directory contains the repositories credentials. Access to it means the credentials could be stolen.
Cryptomaterial theft - if not accessed directly in the Application Repository, the Services Container is able to download all the cryptographic material, which can be then exposed to the attacker.
Altering the run-time system behavior - there are multiple ways of influencing it.

PEP

The PEP is a component to be deployed in a demilitarized zone. Furthermore, it might be deployed in a container that is not under DirX Access control but still must be under the control of the system administrator.

What does a breach mean?

Privileged access to the services - the client component provides privileged access to the Services container and can in this way alter the run-time system behavior.
Cryptomaterial theft
- The instance file system directory contains the client-side secure communication keystore.
- The privileged role may be leveraged via the NCPS protocol to download the features keystores.

DirX Access Keystores

DirX Access differentiates between keystores and external communication keystores. The next sections describe these keystore types in detail.

System Keystores

System keystores are keystores that DirX Access uses for secure communication between its components; in this case, the Services container on one side and internal client components on the other. The following system building blocks are considered to be internal client components:

PEPs

The communication is performed via the REST Web Service endpoints that are explicitly appointed to serve for the communication with the DirX Access internal clients. These endpoints are by default protected by the system keystores that shouldn’t be used for any other purpose, and especially shouldn’t be transferred to any third party.

DirX Access currently supports the following ciphers for the keys employed in the system keystore: RSA, DSA, ECDSA.

DirX Access automatically generates the system keystores (and the keying material they contain) on the deployment of the first DirX Access server instance. Deployment of any additional server instance does not trigger the generation – the already generated keystores are used. The default values for the initial system keystores are as follows:

Algorithm: RSA
Key size: 2048b
Validity period length: 3650 days

attachments/att++_++2++_++for++_++112001030

Figure 1. Deployment of System Keystores

As shown in the figure, the system trust keystore (ST) contains the cert-sign.dirxaccess key representing the certification authority that signs the certificates of the secure communication keys.

Security Considerations

The use of public key cryptography for internal (system) communication in DirX Access has the following specifics:

Services containers share the same secure communications server (SCS) key (which is currently a must),
Clients share the same secure communications client (SCC) key (which can be manually changed),
There are no revocation mechanisms.

This approach is chosen mainly to simplify the otherwise complex PKI infrastructure and to ease the task of key replacement throughout the entire system. As a result, in the case of any security breach, all keys must be replaced, for which DirX Access provides an automatic generation mechanism. This means that system keystores cannot be used in any other use cases.

SCS is used to protect the following components:

Distributed cache - support of the SSL/TLS connection for the cache must be enabled in the cluster configuration. See the chapter “Administrative Tasks” in this guide for details.
Dedicated REST Web Services endpoints
HTTPS port - typically, this port exposes following applications and services:
- DirX Access Manager - enables handling all the cryptographical material and thus is not to be deployed externally.
- SOAP WebServices.

In addition to the initialization of communication security from the client side, the SCS keys provide also an implicit authentication mechanism: any component able to provide the SCS gets privileged access to DirX Access Services API.

System Keystore Types

This section describes the parameters of all the types of system keystores and the cryptographic material they contain.

System Trust (ST) Keystore

Used for: Signing of the system keystores.
Password: If generated using the default generation process, the password remains secret even to the administrator. Both the keystore and the private key it contains are protected by the same password. The password is either:
- Supplied via configuration (Key management | System | Import | Password),
- Generated randomly on the default generation of a new system trust keystore.
Keys:
- cert-sign.dirxaccess
  - Key usage: Certificate signing
  - Is CA: true
  - Issuer: self-signed
  - Subject name: cn=DirX Access Certification Authority,o=instance_name, where instance_name is the value of the instance.name property in the dirxaccess.properties file
  - Password: see ST password
  - Used for: Signing of the system keystores for secure communication between DirX Access components.

Secure Communication Server (SCS) Keystore

Used for: Securing the port for SSL/TLS connection in the Services container as both keystore and truststore.
Password: Equal to the password of the system trust keystore. If generated using the default generation process, the password remains secret even to the administrator. Both the keystore and the private key it contains are protected by the same password.
Keys:
- sec-comm.server.dirxaccess
  - Key usage: Key encipherment, Data encipherment, Key agreement, Encipher only
  - Is CA: false
  - Issuer: cert-sign.dirxaccess issuer
  - Subject name: cn=Secure Communication,o=instance_name
  - SubjectAlternativeName: DNSNames = server_hostnames, where server_hostnames are all “Server hostname” parameters of all configured DirX Access servers in Servers | Services.
  - Password: see SCS password
  - Used for: Secure communication – see the relevant keystore description.
Certificates:
- cert-sign.dirxaccess.trusted
  - For key: cert-sign.dirxaccess

Secure Communication Client (SCC) Keystore

Used for: Securing the port for SSL/TLS connection in the DirX Access clients as both truststore and keystore.
Password: Randomly generated, different from the password of the system trust keystore. Both the keystore and the private key it contains are protected by the same password.
Keys:
- sec-comm.client.dirxaccess
  - Key usage: Digital signature, TLS web client authentication
  - Is CA: false
  - Issuer: cert-sign.dirxaccess issuer
  - Password: see SCC password
  - Used for: Secure communication – see the relevant keystore description.
  - Certificates:
- cert-sign.dirxaccess.trusted
  - For key: cert-sign.dirxaccess

Updating System Keystores

The change of a currently used system trust keystore (and related secure communication keystores) can be motivated by multiple causes: the end of its validity period, the leak of related private keys, a change of company security policy and so on. Any company security policy can be applied to the system keystores due to the ability to supply custom keystores.

The process of updating the system keystores is tightly bound to changing the system trust keystore and is as follows:

Introduce new system trust keystore either by:
1. Using the default generation mechanism (see the section “Generating Default Keystores”)
2. Importing a custom system trust keystore (see the section “Importing a Custom ST”).
The corresponding secure communication server and client keystores are generated with names {ST}.sec-comm.server, {ST}.sec-comm.client where {ST} equals the name of the parent system trust keystore. The secure communication keystores are generated with the same security parameters (key algorithm, key size, signature algorithm) as the parent system trust keystore.
Distribute the secure communication client keystore to the internal client components. For more information, see the section “SCC keystore distribution”.
Switch the currently used system trust keystore by clicking the Use button on the System Trust page with the chosen system trust keystore selected or by using DirX Access Console (See the section “Key Management” in the “Administrative Tools” chapter).
Restart all DirX Access Services containers and internal client components. This point represents the overall downtime of the whole system during the update of the used system keystores.

Generating Default Keystores

The security parameters for the keying material can be set up with DirX Access Manager’s Key Management | System | Generate Default configuration page. See the section “Managing System Keystores” in the “Administrative Tasks” chapter of this guide for details.

Importing a Custom ST

You can replace the system trust keystore that is currently in use with a different one using either DirX Access Manager (see the section “Managing System Keystores” in the “Administrative Tasks” chapter of this guide) or DirX Access Console (see the section “Key Management Commands” in the “Administrative Tools” chapter of this guide).

There are several rules that must be valid for the imported ST:

The alias of the CA key pair must be cert-sign.dirxaccess.
The password of the keystore must be equal to the password of the CA key pair it contains.
The CA key pair must be of one of the supported ciphers (RSA, DSA, ECDSA), must be a CA according to its basic constraints, and the key usage must be at least cRLSign and keyCertSign.

Importing Custom SCS and SCC Keystores without ST

You can import the SCS and SCC without the ST using DirX Access Manager or DirX Access Console. Before performing this task, make sure you are familiar with the SCS and SCC structure discussed in the section “Keystore Types”.

SCC Keystore Distribution

The SCC keystore is used for communication between services and internal client components. The deployment of any internal component incorporates a deployment of this keystore. The keystore location can typically be configured via DirX Access Manager (see the “Administrative Tasks” chapter in this guide).

You can update the SCC using DirX Access Manager. In the Key management | System | Export page. The SCC for the selected system trust keystore can be exported into a file {ST}.sec-comm.client.p12. The page also contains the password for the given keystore to be set up in the appropriate configuration. This configuration differs according to the type of the client and is typical according to the type of the container. Actual configuration may differ.

Apache httpd PEP

PEP location: containerDir/modules

{ST}.sec-comm.client.p12 location: containerDir/conf

PEP configuration: containerDir/conf/dirxaccess.conf

Servlet Filter PEP

PEP location: containerDir/webapps/webapp.war/WEB-INF/lib

{ST}.sec-comm.client.p12 location: depends on the container hosting the protected web-application (containerDir/conf for the Apache Tomcat PEP)

PEP configuration: containerDir/webapps/webapp.war/WEB-INF/web.xml

Apache Tomcat PEP

PEP location: containerDir/lib

{ST}.sec-comm.client.p12 location: containerDir/conf

PEP configuration: containerDir/conf/server.xml

Jetty PEP

PEP location: containerDir/lib/ext

{ST}.sec-comm.client.p12 location: containerDir/etc

PEP configuration: containerDir/etc/jetty.xml

DirX Access Services container

PEP location: instanceDir/../../plugins

{ST}.sec-comm.client.p12 location: instanceDir/etc/keystores

PEP configuration: instanceDir/etc/jetty/config.xml

DirX Access WebApplications container

PEP location: instanceDir/../../plugins

{ST}.sec-comm.client.p12 location: instanceDir/etc/keystores

PEP configuration: instanceDir/etc/jetty/config.xml

Features Keystores

Features keystores are intended to be used in DirX Access use cases; consequently, they need to contain the appropriate keys and/or certificates. Typically, these keystores are used for authentication (X.509, FIDO) and federation (SAML, OAuth, WS-Federation).

Importing a Keystore

The cryptographic material contained within a keystore of this type is typically used in an interaction with third-party components. As a result, we strongly recommend making the material part of the publicly-known PKI (for example, certificates issued by public CA). For more information, see the section “Managing Features Keystores” in the “Administrative Tasks” chapter of this guide.

Generating a Sample Keystore

DirX Access supports the generation of sample keystores. These keystores can be used as a template for the entries that the production-ready keystore should contain. Security parameters for sample keystores can be set with DirX Access Manager’s Key Management | Features | Generate Sample configuration page. See the section “Managing Features Keystores” in the “Administrative Tasks” chapter of this guide for more information.

DirX Access currently provides for the generation of sample keystores for the following use cases: certificate verification (X.509 and FIDO authentication), identity provider (SAML, OAuth, WS-Federation), and service provider (SAML, OAuth).

How Features Keystores Protect DirX Access Components

This section describes how features keystores protect the DirX Access components.

Authentication Method FIDO

For more information, see the section “Configuring FIDO Authentication Methods” in the “Administrative Tasks” chapter of this guide.

Authentication Method SAML

All the relevant certificates from all peer metadata are used to verify the assertion signature. Each SAML endpoint contains its own in-memory-stored virtual truststore.

Authentication Method X.509

The truststore containing certificates, any of which can be used as a root for the construction of the certificate path during certificate validation, is set by the “Keystore identifier”, ”Keystore password” tuple. A sample keystore for this use case can be generated via DirX Access Manager’s Key Management | Features | Generate Sample.

OAuth Server / Client

For more information, see the chapter “OAuth 2.0 Authorization Framework”.

SAML

Elements Signing and Decryption

SAML element signing and encryption is fully configurable via the SAML endpoint configuration object. For more information, see the section “Configuring SAML FEP Settings” in the “Administrative Tasks” chapter. A sample keystore for this use case can be generated via DirX Access Manager’s Key Management | Features | Generate Sample.

SAML Application

The SAML web application uses the same private keys for assertion and communication security as described in section “SAML Element Signing and Encryption”.

For verifying the signatures or encrypting the SAML elements, the certificates must be provided in all configured peer SAML metadata. Each SAML endpoint contains its own in-memory-stored virtual truststore.

WS-Federation/WS-Trust

Elements Signing and Decryption

The WS-Federation/WS-Trust element signing and encryption is fully configurable via the WS-Federation endpoint configuration object. For more information, see the section “Configuring WS-Federation STS Endpoint Settings” in the “Administrative Tasks” chapter. A sample keystore for this use case can be generated via DirX Access Manager’s Key Management | Features | Generate Sample.

WS-Federation Application

The WS-Federation Application consists of two accessible interfaces: WS SOAP interface and Passive Requestor Profile (PRP) interface. The PRP is bound to the SOAP interface. Both sides use the same signing key (by default, federation-sign.dirxaccess) originating from the same keystore. A sample keystore for this use case can be generated via DirX Access Manager’s Key Management | Features | Generate Sample.

Advanced note: To make the SOAP interface accessible via signed/encrypted communication from an entity other than the DirX Access PRP client, you must change both sides (wsit-client-federation.xml, dxa-common-sts-policy.wsdl and WsitSelector.java, WsitCallbackHandler.java).

XACML Policy Querying/Managing

The XACML policy queries elements are validated by the truststore defined in related PDP configuration of DirX Access Manager.

External Communication Keystores

The external communication keystores protect the communication channels of the DirX Access system to external components. The content of these keystores must be bound to a publicly-known PKI; however, default keystores can be generated to be able to run the product out-of-the-box. These default keystores must be replaced when the deployment is moved into a production environment.

Services Container

The Services Jetty container can communicate with any client via HTTPS. For the internal client components, the SCS is used to protect the Services container (hence, SCC must be used on the client side). The HTTPS port that faces the third-party clients must be protected by a keying material wired into a publicly-known PKI.

As a result, the Jetty container configuration enables establishing a custom port with a custom keystore and truststore (http.services.server). See the section “How to Set up the Production Environment” for details.

The custom HTTPS port is important due to the fact that DirX Access enables deploying the following components into the Services container:

DirX Access Manager
RESTful services
SOAP Web Services

OSGi Console SSH Key Pair

The key pair that protects an SSH port (osgi.server) is generated by the server side of the OSGi console and is completely independent of any configuration. Its function is to protect the server side via SSL/TLS. The key is stored in the PKCS#12 keystore at the address set by the ssh.server.keystore system parameter (by default, ./configuration/ssh_server_keystore.p12). The OSGi console manages its generation automatically; that is, it is auto-generated when needed. The default cipher used is DSA with 1024b key size. The default password is dirxaccess. The keystore contains a single private key with the alias private_key and with a self-signed certificate.

You can replace the keystore and protect the console with a key pair of your own choice with the subsequent required parameters: cipher: DSA, private key alias: private_key, password: configurable via Java system property ssh.server.keystore.password (by default dirxaccess).

LDAP

See javax.net.ssl.truststore in the Services container.

HTTPS Client

The implementation of several use cases deployable in the Services container require the use of the HTTP client. The HTTPS client truststore is defined globally for the Services container instance by specifying the following properties in the Services container instance configuration file etc/wrapper.conf:

# Truststore for SSL/TLS client connections from server
wrapper.java.additional.x=‑Djavax.net.ssl.trustStore=PATH
wrapper.java.additional.x+1=‑Djavax.net.ssl.trustStorePassword= PASSPHRASE

where:

The x and x+1 numbers need to be replaced with unique numbers within the wrapper.java.additional.* properties.
PATH is a full path to a Java keystore containing trusted CA or end entity certificates.
PASSPHRASE is a passphrase protecting the keystore.

To enable the client to communicate via HTTPS, the corresponding certificates must be present in this keystore. Namely:

OAuth client: For each configured partnership with OAuth Identity Provider, the corresponding certificate must be included.

How to Set up the Production Environment

DirX Access enables an easy deployment to be able to work with and configure a running system. For this reason, there are a vast number of default configuration parameters and artifacts, including several default keystores and their security parameters.

This section gives an overview of the mandatory and recommended changes to the configuration with respect to keystore management.

Mandatory Tasks

This section describes the mandatory tasks that need to be performed to set up a production environment.

Services Container HTTPS Keystore

Change the keying material for the HTTPS port assignments. The new keying material should be trusted by the clients (either via enterprise CA or public CA).

System Keystores Update

Customize a validity period for system keystores and update them regularly before they expire.

Recommended Tasks

This section describes recommended tasks to be performed when setting up a production environment.

LDAPS Connections

See the section “Setting up LDAP over SSL/TLS” in the DirX Access Installation Guide.

Services Container HTTP(S) Connection

See the section “System Keystores” -> “Security Considerations” in this chapter.

OSGi Console

Consider limiting accessibility to the OSGi Console port.