Skip to content
Documentation

Cryptography Configuration

This guide describes how to configure cryptography settings for PowerTSM components.

The cryptography configuration tells a HAKOM product which X.509 certificates (RSA key pairs) are available to it, and under which logical name. It does not enable encryption by itself. Instead, it is the key directory that other features look up by name.

The main use case is keeping confidential values out of the configuration in clear text. The most common example is a database password:

  1. Encrypt the value with HAKOM.Cryptography.Console, using one of the configured certificates.
  2. Put the resulting base-64 string into the configuration and mark it as encrypted:
<Setting Name="Password" Encrypted="true" Certificate="Shared Development Key">TaE+e+...</Setting>
  1. When the product loads the repository configuration, it looks up the certificate named in the Certificate attribute (or Default, if the attribute is omitted) and decrypts the value transparently with its private key.

This works for the Settings and ElevatedSettings of a repository, both in HAKOM.xml and in environment variables. The private key needed for decryption is not part of the configuration. It stays in the certificate store of the operating system user, or in a PFX file. With a PFX file, its password is part of the configuration, so protect the configuration accordingly.

Applications built on the .NET API can use the same certificates through ICryptographyService to encrypt, decrypt, sign and verify their own data.

With FileSystem, the PFX password is stored in the configuration in clear text, so the protection depends entirely on access to the PFX file. It only adds security if the PFX file is stored separately from the configuration and is readable by fewer people, for example mounted as a secret into a container or placed in a directory that only the service account can read. If the PFX file is as accessible as the configuration, the encrypted values are effectively not protected. Prefer LocalUser where possible.

All cryptography settings are located under the following base path:

HAKOM:Cryptography
Cryptography
└─ CertificateStorage
├─ LocalUser
│ └─ Certificates
│ └─ Certificate
│ └─ {CertificateName} (value: SHA-1 thumbprint)
└─ FileSystem
└─ Certificates
└─ Certificate
└─ {CertificateName}
├─ FileName
└─ Password

{CertificateName} is the logical name a certificate is addressed by, for example in the Certificate attribute of an encrypted setting. The name Default is used whenever no name is given explicitly.


<HAKOM>
<Cryptography>
<CertificateStorage>
<LocalUser>
<Certificates>
<Certificate Name="Shared Development Key">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate>
<Certificate Name="Default">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate>
</Certificates>
</LocalUser>
</CertificateStorage>
</Cryptography>
</HAKOM>

Configure the certificate storage settings for your application.

Path: HAKOM:Cryptography

Element Type Default Required Description
CertificateStorage object — ✓ Container for the different certificate storages.
CertificateStorage:{StorageType} object — ✓ Type of certificate storage to configure. Allowed values: LocalUser, FileSystem.
LocalUser FileSystem
Where the key lives Personal certificate store of the operating system user (CurrentUser\My) PFX file on disk, protected by a password
Certificate identified by SHA-1 thumbprint File name and password
Typical use Service running under a dedicated account; the key never appears in a file Automated or containerized deployments, or a key that has to be used on several hosts or by several accounts
Keep in mind The certificate must be installed for the exact account the service runs under, not for the account that installed the product The PFX password is part of the configuration, so protect the file and the configuration with file system permissions

LocalUser and FileSystem can be configured at the same time, each with its own set of certificates:

<Cryptography>
<CertificateStorage>
<LocalUser>
<Certificates>
<Certificate Name="Default">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate>
</Certificates>
</LocalUser>
<FileSystem>
<Certificates>
<Certificate Name="Reporting Key">
<FileName>reporting.pfx</FileName>
<Password>securepassword</Password>
</Certificate>
</Certificates>
</FileSystem>
</CertificateStorage>
</Cryptography>

When a certificate is requested by name, the product checks each configured storage and uses the first one that returns it. A storage is skipped if it has no entry with that name, or if the entry cannot be loaded, for example because the PFX file is missing, the password is wrong, or the thumbprint is not installed for the current user. If no storage returns the certificate, the operation fails with a “certificate not found” error.

This also allows one configuration to serve different hosts: define the same certificate name in both storages, and whichever one is actually available on a given machine answers the request.

Configure individual certificates for each storage type.

Path: HAKOM:Cryptography:CertificateStorage:{StorageType}:Certificates:Certificate

The LocalUser storage type allows you to configure certificates using their SHA-1 thumbprint.

Element Type Default Required Description
Name string — ✓ Name of the certificate. Allowed values: any string.
Certificate string — ✓ SHA-1 thumbprint of an installed certificate, given as the value of the Certificate element. Allowed values: a valid SHA-1 hash.

flask Certificates from the LocalUser store

Section titled “ Certificates from the LocalUser store”
<Cryptography>
<CertificateStorage>
<LocalUser>
<Certificates>
<Certificate Name="Shared Development Key">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate>
<Certificate Name="Default">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate>
</Certificates>
</LocalUser>
</CertificateStorage>
</Cryptography>
© 2026 Volue.Version v0.6.38017 November 2026