Crypto-material Management

This article 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 multiple layers.

A persistence layer is represented by the Application and User Repositories and DirX Access Cache Servers providing data to a layer of DirX Access Servers. DirX Access Servers can communicate to internal client components such as the PEPs and to external components in the internet. Optionally, additional layer can be represented by DirX Access Bridge.

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 client’s 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.

DirX Access Cache Server

The DirX Access Cache Server is a component containing both persisted and short-lived data. It doesn’t contain the SSO sessions per se, however, may contain federation tokens and intermediary protocol messages.

What can a breach mean?

Refresh token theft - an attacker with access to refresh token cache/persistence can read the entries and use them in their environment
Private data theft - the caches contain user-related (potentially private) data

What doesn’t a breach mean?

Altering configuration data - there’s no configuration data stored in the DirX Access Cache Server
Ability to create a new SSO session - no material enabling creation of new session is in the DirX Access Cache Server

DirX Access Server

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, e.g. 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 to download the features keystores.

DirX Access Crypto Containers

Any cryptomaterial used in the Services Container is referenced through Crypto Container configuration in the Application Repository. The configuration references the Keystore configuration and describes the intended usage. DirX Access does not have extra Keystore configuration types to differentiate whether the actual usage is for secure communication between its components or external purposes (DirX Access features).

The description of the intended usage is given by entries referencing the cryptographic material within the referenced keystore. Each entry corresponds to the cryptomaterial entry within the referenced keystore and is described via type, alias, password, algorithm, validity and paired alias as a counterpart entry within the same keystore, e.g. paired alias of a certificate entry to a private key entry. Please see Administrative Tasks for more information about Crypto Container and Keystore configuration types.

TODO: key rotation

Use Cases

Certificate signing

TODO

Securing the port of the Services Container for SSL/TLS connection

A port of the Services Container is opened by a PortAssignment configuration object. When the port is to be protected by SSL/TLS, the PortAssignment object sets useSsl to true and references a Crypto Container, not a Keystore directly:

{
  "@odata.type": "#net.atos.dirx.access.apprepo.api.config.cluster.PortAssignment",
  "key": "${dxaServerPort}",
  "portNumber": ${dxaServerPort},
  "useSsl": true,
  "keystoreId": {
    "key": "system.trust.sec-comm.server",
    "type": "net.atos.dirx.access.apprepo.api.config.crypto.CryptoContainer"
  }
}

The referenced Crypto Container in turn references the Keystore configuration object holding the actual crypto material, the password protecting it, and the entries that are expected inside:

the KEY_PAIR entry sec-comm.server.dirxaccess - the server key and its certificate presented during the TLS handshake,
the CERTIFICATE entry sec-comm.server.dirxaccess.trusted - the paired certificate of the key pair,
the CERTIFICATE entry cert-sign.dirxaccess.trusted - the certification authority certificate, making the container usable as a truststore as well.

Both objects are created together by the dxaConfigPortAssignmentSsl.json template, which the DirX Access Installer applies for every deployment approach.

The chain is therefore port assignment → crypto container → keystore. Whenever the crypto material behind the HTTPS port is exchanged - for example because an own system trust is deployed and thus the secure communication server keystore is generated under a different keystore identifier - it is not sufficient to import the new keystore. The Crypto Container referenced by the port assignment has to be updated to point to the new Keystore configuration object, or the port assignment has to be pointed to a new Crypto Container. Additionally, the keystorePassword and the entry password values of the Crypto Container have to match the passwords of the new keystore.

Establishing the internal client SSL/TLC context

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 keystores that shouldn’t be used for any other purpose, and especially shouldn’t be transferred to any third party.

TODO

DirX Access Features

TODO

How to Set up the Production Environment

This chapter describes how to get from the crypto material that the DirX Access Installer prepares out of the box to crypto material that is fully under the control of the administrator.

All the steps below happen in the startup folder of the instance, between the end of the installation and the first startup of the DirX Access Server. The files placed there are applied by the Direct Application of System Actions, Configuration and Shadow User Tree in alphabetical order.

The Default Crypto-material Chain

Even the most basic Business-service-only Server Approach already produces a complete crypto-material chain. The files responsible for it are described in Startup Folder Prepared by the Installer and are:

startup/sysactions/dxaDefault1SysActionCryptoGenerateSystemTrust.json - generates the system trust keystore system.trust: a self-signed certification authority with the key pair cert-sign.dirxaccess that signs all dependent DirX Access system keystores.
startup/sysactions/{NN}_dxaCryptoGenerateKeystoreSecCommServer.json - generates the secure communication server keystore system.trust.sec-comm.server, signed by the above certification authority.
startup/config/{NN}_dxaConfigPortAssignmentSsl.json - creates the HTTPS port assignment and the crypto container referencing that keystore.

The default chain is self-contained and self-signed. It is perfectly suitable for the internal secure communication between the DirX Access components, but the certificate presented at the HTTPS port will not be trusted by any external client unless the certification authority certificate is distributed to it - see Making the Certification Authority Trusted by the Clients.

Deploying an Explicit System Trust

If no explicit system trust is imported, dxaDefault1SysActionCryptoGenerateSystemTrust.json is applied and the system trust is generated by DirX Access itself.

If an explicit system trust is to be deployed instead, exchange this file during the deployment - before the first startup of the server - for a file that imports the prepared keystore. Simply deleting the file is possible as well, but then no system trust exists at all and the generation of the secure communication server keystore, which depends on it, fails.

Keep the following rules in mind:

The replacement file has to be applied before the generation of any dependent keystore. The files located directly in startup/sysactions/ are read in alphabetical order of their file names, so use a name that sorts before the file generating the secure communication server keystore - for example a 10_/11_ numbering as in the examples below.
The file must be placed directly into startup/sysactions/. Subfolders are not traversed and their content is silently ignored.
Note that files whose name starts with dxaDefault are always applied first, before all the other files. Once the default system trust generation file is removed, this special ordering no longer plays a role.
The rules for a custom system trust listed in Keystore Management apply: the alias of the certification authority key pair must be cert-sign.dirxaccess, the password of the keystore must be equal to the password of the key pair it contains, and the key pair must be a CA according to its basic constraints with at least the keyCertSign and cRLSign key usages.

Creating a System Trust with OpenSSL

A system trust keystore can be created completely outside of DirX Access, for example with OpenSSL 3.x. Only the crucial parts are described here.

Describe the certificate profile in an OpenSSL configuration file. The extensions are what DirX Access expects from a certification authority:

[ req ]
distinguished_name = dn
x509_extensions    = v3_ca
prompt             = no

[ dn ]
O  = My-Company
CN = DirX Access Certification Authority

[ v3_ca ]
keyUsage             = critical,keyCertSign,cRLSign
basicConstraints     = critical,CA:TRUE
subjectKeyIdentifier = hash

Generate the key and the certificate. Two variants are possible, and the second one is the usual one in a production environment.

Variant A - self-signed certification authority. The key and the certificate are created in one step. The resulting certificate is self-signed - creating the system trust manually does not make it a certificate issued by a public certification authority; it only puts its generation, its parameters and its password under your control:

openssl req -x509 -config system.trust.rsa.openssl.cnf -newkey rsa:3072 -sha256 -nodes -days 3650 -keyout system.trust.key -out system.trust.crt

Variant B - certification authority signed by an already trusted certification authority. In a production environment the system trust is usually not self-signed but subordinated to the certification authority that the organization already operates and that the clients already trust. Instead of a certificate, a certificate signing request is created and submitted to that certification authority:

openssl req -new -config system.trust.rsa.openssl.cnf -newkey rsa:3072 -sha256 -nodes -keyout system.trust.key -out system.trust.csr

For the request, the configuration file has to offer the extensions as requested extensions, so add the following line to its [ req ] section:

req_extensions = v3_ca

The issuing certification authority returns the signed certificate - system.trust.crt in the examples below - together with the certificates of the chain up to its root.

The certificate issued for the system trust must again be a certification authority certificate: CA:TRUE in its basic constraints and at least the keyCertSign and cRLSign key usages. DirX Access uses the system trust to sign the secure communication keystores, so an ordinary TLS server certificate cannot be used for this purpose. Most corporate public key infrastructures issue such a certificate only through a dedicated subordinate certification authority request. If the organization cannot issue a subordinate certification authority certificate, Variant A remains the only option.

With Variant B, the certificate presented at the HTTPS port chains up to a certification authority that the clients already trust, so no certificate has to be distributed to them. With Variant A, the self-signed certificate has to be made trusted explicitly - see Making the Certification Authority Trusted by the Clients.

Pack the key and the certificate into a PKCS#12 keystore using the alias that DirX Access expects. The export password becomes both the keystore password and the private key password:
```
openssl pkcs12 -export -inkey system.trust.key -in system.trust.crt -name cert-sign.dirxaccess -passout pass:{keystore_password} -out system.trust.p12
```
With Variant B, the certificates of the issuing chain belong into the keystore as well, so that the complete chain can be presented during the TLS handshake:
```
openssl pkcs12 -export -inkey system.trust.key -in system.trust.crt -certfile ca-chain.pem -name cert-sign.dirxaccess -passout pass:{keystore_password} -out system.trust.p12
```
Produce the single-line Base64 representation of the keystore file:
```
openssl base64 -A -in system.trust.p12
```

The printed string is the Base64 encoding of the whole PKCS#12 file, on a single line, without any line breaks or PEM header and footer. This is exactly the representation that has to be put into the keystore field when importing any keystore into DirX Access - not only the system trust.

OpenSSL 3.x writes the PKCS#12 container with AES-256-CBC / PBKDF2 / SHA-256 defaults, which are read natively by the Java runtime used by DirX Access.

Migrating an Existing System Trust and Secure Communication Server Keystore

A freshly installed instance does not have to start with new crypto material. When an existing installation is moved to another host, re-installed or upgraded by a side-by-side installation, its system trust and its secure communication server keystore can be taken over. Nothing is generated in this case - both keystores are imported.

Collect the keystore files of the existing installation. They are either archived from the time when they were created, or they are exported from the running installation with DirX Access Manager on the Key Management | System | Export page, which also shows the password belonging to the exported keystore. See Keystore Management for the structure and the naming of the system keystores. The result is one PKCS#12 file per keystore - the system trust and the secure communication server keystore, whose configuration key is derived from the system trust as {ST}.sec-comm.server.

Produce the single-line Base64 representation of every collected file. This is the only form in which a keystore can be put into a system action file:

openssl base64 -A -in system.trust.p12
openssl base64 -A -in system.trust.sec-comm.server.p12

Without OpenSSL on the machine, PowerShell produces the same string:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("system.trust.p12"))

The string must encode the whole keystore file and must be on a single line, without any line breaks and without a PEM header and footer. The Windows certutil -encode command is therefore not suitable, because it wraps the output and adds the PEM envelope.

Defuscate the keystore password if necessary. Passwords taken over from the configuration of the existing installation may be stored in the obfuscated form, recognizable by the protected: prefix - see Password/Keys Obfuscation. The import system action file needs the password that really protects the keystore, so such a value has to be defuscated first.

The obfuscation and the defuscation are done with the Obfuscator tool, which is delivered as the DirX Access Extensions component and can be downloaded from the Identity and Access Management Support Portal. For its usage, see the documentation delivered with the tool.
Prepare one import file per keystore as described in Importing the System Trust and place them directly into startup/sysactions/, for example as 10_dxaCryptoImportSystemTrust.json and 11_dxaCryptoImportKeystoreSecCommServer.json. The secure communication server keystore is imported with the same ImportKeystoreSysAction, only with its own key, keystore and password:
```
{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.ImportKeystoreSysAction",
        "key": "system.trust.2026.sec-comm.server",
        "keystore": "MIIQ1QIBAzCCEIsGCSqGSIb3DQEHAaCCEHwEghB4MIIQdDCCBusGCSqGSIb3DQEHBqCCBtw...",
        "password": "{keystore_password}"
    }
}
```
Remove the files that would create the crypto material anew. Both dxaDefault1SysActionCryptoGenerateSystemTrust.json and the dxaCryptoGenerateKeystoreSecCommServer.json file are exchanged for the two import files, otherwise a new system trust and a new server keystore are created next to the migrated ones.
Reference the migrated keystore in the crypto container of the HTTPS port assignment, as described in Referencing the New Crypto Material.

A migrated secure communication server keystore keeps the subject, the dnsNames and the validity period of its original certificate. If the host name changes or the certificate is about to expire, import only the system trust and let the server generate a new server keystore from it, as described in Generating the Secure Communication Server Keystore.

As long as the system trust is migrated unchanged, the secure communication client keystores already distributed to the internal client components stay valid and do not have to be redistributed.

Importing the System Trust

The Base64 string is placed into an ImportKeystoreSysAction system action file that replaces dxaDefault1SysActionCryptoGenerateSystemTrust.json in the startup folder, for example as startup/sysactions/10_dxaCryptoImportSystemTrust2026.json:

{
    "action": {
        "@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.ImportKeystoreSysAction",
        "key": "system.trust.2026",
        "keystore": "MIIN6AIBAzCCDZ4GCSqGSIb3DQEHAaCCDY8Egg2LMIINhzCCBXoGCSqGSIb3DQEHBqCCBWs...",
        "password": "{keystore_password}"
    }
}

key is the identifier of the resulting Keystore configuration object. It is freely choosable - the example uses system.trust.2026 to express the year of the rollover - but it has to be used consistently in all the dependent files.
keystore is the single-line Base64 representation of the PKCS#12 file produced above.
password protects both the keystore and the private key it contains.

Generating the Secure Communication Server Keystore

The DirX Access Server is able to generate the secure communication server keystore itself, and by default it does so: the dxaCryptoGenerateKeystoreSecCommServer.json template is prepared for this purpose by the installer.

The template looks for the issuing system trust under the keystore identifier system.trust and with the default password:

"issuer": {
  "keystoreId": {
    "key": "system.trust",
    "type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
  },
  "keystorePassword": "{default_password}",
  "keyPairAlias": "cert-sign.dirxaccess",
  "pairedAlias": "cert-sign.dirxaccess.trusted"
}

If an explicit system trust was imported under a different key or with a different password, these values have to be exchanged accordingly. The same applies to the key and password of the generated keystore itself.

The following properties of the generated KEY_PAIR entry determine whether the resulting certificate is usable as a TLS server certificate and have to be reviewed for every deployment:

Property Description

Property	Description
`keyUsage`	The X.509 key usage extension as a bit string of nine characters, in the order defined by RFC 5280: `digitalSignature`, `nonRepudiation`, `keyEncipherment`, `dataEncipherment`, `keyAgreement`, `keyCertSign`, `cRLSign`, `encipherOnly`, `decipherOnly`. The template default `101000000` therefore sets `digitalSignature` and `keyEncipherment`, which covers the common TLS cipher suites. If a key agreement based cipher suite has to be supported, the corresponding bits have to be set as well, for example `101110010`.
`extendedKeyUsage`	The object identifiers of the extended key usage extension. The value `1.3.6.1.5.5.7.3.1` stands for TLS server authentication and is mandatory for a certificate presented at an HTTPS port.
`dnsNames`	The DNS names put into the subject alternative name extension. The certificate is accepted by a client only if the host name used to reach the server is among them. The template pre-fills the host name of the instance and the publicly reachable host name; all further names - the load balancer name, any alias and the names of all other servers sharing the keystore - have to be added manually.
`subjectDn`	The subject distinguished name of the generated certificate.

keyUsage

The X.509 key usage extension as a bit string of nine characters, in the order defined by RFC 5280: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly. The template default 101000000 therefore sets digitalSignature and keyEncipherment, which covers the common TLS cipher suites. If a key agreement based cipher suite has to be supported, the corresponding bits have to be set as well, for example 101110010.

extendedKeyUsage

The object identifiers of the extended key usage extension. The value 1.3.6.1.5.5.7.3.1 stands for TLS server authentication and is mandatory for a certificate presented at an HTTPS port.

dnsNames

The DNS names put into the subject alternative name extension. The certificate is accepted by a client only if the host name used to reach the server is among them. The template pre-fills the host name of the instance and the publicly reachable host name; all further names - the load balancer name, any alias and the names of all other servers sharing the keystore - have to be added manually.

subjectDn

The subject distinguished name of the generated certificate.

An adapted file, referencing the imported system trust, then looks as follows:

{
	"action": {
		"@odata.type": "#net.atos.dirx.access.sysactions.api.action.crypto.GenerateKeystoreSysAction",
		"key": "system.trust.2026.sec-comm.server",
		"password": "{keystore_password}",
		"entries": [
			{
				"type": "KEY_PAIR",
				"alias": "sec-comm.server.dirxaccess",
				"from": 0,
				"to": 0,
				"pairedAlias": "sec-comm.server.dirxaccess.trusted",
				"subjectDn": "cn=Secure Communication,o=My-Company",
				"keyUsage": "101110010",
				"extendedKeyUsage": [ "1.3.6.1.5.5.7.3.1" ],
				"dnsNames": [ "my-server1.my-company.example" ],
				"issuer": {
					"keystoreId": {
						"key": "system.trust.2026",
						"type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
					},
					"keystorePassword": "{keystore_password}",
					"keyPairAlias": "cert-sign.dirxaccess",
					"pairedAlias": "cert-sign.dirxaccess.trusted"
				}
			},
			{ "type": "CERTIFICATE", "alias": "sec-comm.server.dirxaccess.trusted" },
			{ "type": "CERTIFICATE", "alias": "cert-sign.dirxaccess.trusted" }
		]
	}
}

The secure communication client keystore is created the same way from the dxaCryptoGenerateKeystoreSecCommClient.json template and has to be regenerated from the same system trust and distributed to the internal client components. See Keystore Management for the distribution procedure.

Referencing the New Crypto Material

Generating or importing a keystore alone has no effect on the running system - the crypto material becomes effective only when it is referenced by a Crypto Container and the Crypto Container is referenced by the consuming configuration object.

For the HTTPS port of the Services Container this means adapting the dxaConfigPortAssignmentSsl.json file prepared in startup/config/:

the keystoreId of the Crypto Container has to point to the new Keystore configuration object, for example system.trust.2026.sec-comm.server,
the keystorePassword and the password of every entry have to match the passwords of the new keystore,
the alias values of the entries have to match the aliases contained in the new keystore,
the keystoreId of the PortAssignment object has to point to the Crypto Container.

For the details of this chain, see Securing the port of the Services Container for SSL/TLS connection.

Making the Certification Authority Trusted by the Clients

A self-signed system trust is not known to any client, so a browser opening an HTTPS endpoint of DirX Access reports the page as not secure even though the connection is encrypted correctly. To avoid this, the certificate of the certification authority - not the server certificate - has to be added to the trusted root certification authorities of every client that accesses the server.

This step is needed only for a self-signed system trust, which includes the system trust generated by DirX Access itself. If the system trust was signed by an already trusted certification authority, as in Variant B of Creating a System Trust with OpenSSL, the clients trust the chain already and nothing has to be distributed.

Export the certification authority certificate. If it is not at hand from the creation of the system trust, it can be taken out of the keystore, or exported from the running installation with DirX Access Manager on the Key Management | System | Export page:
```
openssl pkcs12 -in system.trust.p12 -nokeys -clcerts -out system.trust.crt
```
Add the certificate to the Trusted Root Certification Authorities store of the client.
- On Windows, import it into the machine store either with certmgr.msc - Trusted Root Certification Authorities | Certificates | All Tasks | Import - or from an elevated command line:
  certutil -addstore -f Root system.trust.crt
- Firefox maintains its own certificate store: Settings | Privacy & Security | Certificates | View Certificates | Authorities | Import, with the option to trust the certification authority to identify web sites.
- Java-based clients need the certificate in the truststore they use, for example imported with keytool -importcert.
  
  In a managed environment, distribute the certificate to all the clients centrally, for example by a group policy.

A trusted certification authority alone is not enough: the browser also validates the name of the server against the certificate presented at the port. The dnsNames of the secure communication server keystore therefore have to contain the host names under which the server is addressed - see Generating the Secure Communication Server Keystore.

Checklist

Create the system trust outside of DirX Access or accept the generated one.
Exchange dxaDefault1SysActionCryptoGenerateSystemTrust.json for the import system action if an explicit system trust is used.
Adapt the secure communication server keystore generation: issuer keystore identifier and password, keyUsage, extendedKeyUsage, dnsNames and subjectDn.
Regenerate and redistribute the secure communication client keystore.
Adapt the Crypto Container and the HTTPS port assignment to reference the new keystore.
Distribute the certification authority certificate to the trusted root certification authorities of the clients if the system trust is self-signed.
Replace all default passwords - they are publicly known.
Verify the numbering of the files so that the system trust is imported before all keystores derived from it.
Start the DirX Access Server and verify that all the files have been moved into the corresponding used/ subfolders.