Cryptography Configuration
This guide describes how to configure cryptography settings for PowerTSM components.
Purpose
Section titled “Purpose”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:
- Encrypt the value with HAKOM.Cryptography.Console, using one of the configured certificates.
- 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>- When the product loads the repository configuration, it looks up the certificate named in the
Certificateattribute (orDefault, 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.
Configuration Path
Section titled “Configuration Path”All cryptography settings are located under the following base path:
HAKOM:CryptographyConfiguration Structure
Section titled “Configuration Structure”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.
Quick Start
Section titled “Quick Start”<HAKOM> <Cryptography> <CertificateStorage> <LocalUser> <Certificates> <Certificate Name="Shared Development Key">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate> <Certificate Name="Default">51e5e51363c9d1f76c0078aaae45512f7e7f3660</Certificate> </Certificates> </LocalUser> </CertificateStorage> </Cryptography></HAKOM>{ "Cryptography": { "CertificateStorage": { "LocalUser": { "Certificates": { "Certificate": { "Shared Development Key": "51e5e51363c9d1f76c0078aaae45512f7e7f3660", "Default": "51e5e51363c9d1f76c0078aaae45512f7e7f3660" } } }}HAKOM__Cryptography__CertificateStorage__LocalUser__Certificates__Certificate__Shared_Development_Key=51e5e51363c9d1f76c0078aaae45512f7e7f3660HAKOM__Cryptography__CertificateStorage__LocalUser__Certificates__Certificate__Default=51e5e51363c9d1f76c0078aaae45512f7e7f3660Configuration Elements
Section titled “Configuration Elements”Certificate Storage Configuration
Section titled “Certificate Storage Configuration”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. |
Choosing a Storage Type
Section titled “Choosing a Storage Type”| 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 |
Using Both Storage Types
Section titled “Using Both Storage Types”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.
Certificate Configuration
Section titled “Certificate Configuration”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. |
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>The FileSystem storage type allows you to configure certificates using a file path and password.
| Element | Type | Default | Required | Description |
|---|---|---|---|---|
Name |
string |
— | ✓ | Name of the certificate. Allowed values: any string. |
FileName |
string |
— | ✓ | File path to the certificate file. Allowed values: a valid file path. |
Password |
string |
— | ✓ | Password for the certificate file. Allowed values: any string. |
Certificate from a file
Section titled “ Certificate from a file”<Cryptography> <CertificateStorage> <FileSystem> <Certificates> <Certificate Name="Development Key"> <FileName>path/to/certificate.pfx</FileName> <Password>securepassword</Password> </Certificate> </Certificates> </FileSystem> </CertificateStorage></Cryptography>