...

Info
This article includes updates for Smart ID 23.04.14.

This article describes the concept of chained signature for object history in Smart ID Identity Manager.

...

In the object history, all changes on each object (employees, cards, certificates, requests etc.) are tracked. This can, for example, be that data is changed, status (like deactivate card) is changed, or if a process is executed (start Smart ID Mobile App provisioning) etc. This history is signed, so that it is recognized if someone modifies the records in the database. Chained signature means that each entry of the object history is signed. The signature is based on the signature of the previous entry, so it is not possible to add, remove or change an entry without breaking the chain. Thus every manipulation of the object history can the object history can be detected as long as the head of the chain is protected. The chained signature spans over all history entries, regardless of tenant.

Expand

title	Prerequisites

The certificates used for signing and verification need to be valid for digital signatures. Otherwise Identity Manager will fail on writing to the database.
Upgrade to 22.04 (or later) from an earlier version:
1. The parameter commonHistoryService.verificationIntervalMonths in the system properties part of the docker-compose.yml
file
1. file for Identity Manager Operator was renamed to commonHistoryService.historyCutOffDuration in Smart ID 22.04. Make sure you rename it accordingly in your configuration. See also List of Identity Manager system properties.
2. Add/update the following section and configure it as desired (explained further down in this document).
  The default CRON expression for the history cleaning task has been added to be executed on Fridays only. This is a new property added for the history cleaning task:
Code Block
# History cleaning task historyCleaningTrigger.cronExpression = 0 30 0 ? * FRI *
Furthermore, the default CRON expression for the history verification task has changed, so it executes only on Sundays, not daily:
Code Block
# History verification task historyVerificationTrigger.cronExpression = 0 30 0 ? * SUN *
See also Upgrade Smart ID Identity Manager from 21.10 to 22.04

Step-by-step instructions

...

title

file:
Add key for chained signature

Expand

title	Configure chained signature

The keys and certificates used for signing and verification are configured in the encrypt and sign engine's configuration, typically found under engineSignEncryptConfig.xml.

Configure the key used for the chained signature via the property descriptorName of the bean historyServiceSigner. Add the following in the system properties part of the docker-compose.yml

file:

Code Block

Code Block
historyServiceSigner.descriptorName=<name of the descriptor>

If the chained signature is not configured, Tomcat startup will fail with an error message like:

Code Blocktitle

Error message from

Tomcat

Tomcat

Code Block
Error accessing the sign and encrypt engine (5, No descriptor found with name: overwriteMe)

Verify chained signature

Verification consists of traversing over all entries of the object history, regardless of tenant, and verifying its signature.

Expand

title	Manual verification

Verify the chained signatures with a REST service call to this url:
Panel
title URL for manual verification of chained signature
<prime-explorer>/ws/objecthistory/verify[?tenantId=<tenant for login>]
where the tenantId is optional.
The login can be done via basic authentication. For example, if you log in as admin/admin the following header is added, where YWRtaW46YWRtaW4= is the "admin:admin" Base64-encoded:
Code Block
Authorization: Basic YWRtaW46YWRtaW4=
Some REST service clients support convenient entry of basic authentication with fields. If preemptive authentication is offered, you should use that, since the REST service do not ask for authentication, but rather just fail if no authentication is offered.
The result is either 'true' if everything is fine or 'false' if a verification failed. Details about verification errors are listed in a log file.

Note
A successful verification is only possible if at least one entry is already signed.

title

System property: Add user for scheduled task

Expand

title	Scheduled verification

A scheduled job regularly checks the signature chain of the object history. If an error is found, it will send an email to configurable recipients.

As the object history signature spans over all history entries, regardless of the tenant, the verification on a multi tenant system should be done by a dedicated user that belongs to no tenant (that is, it has a null tenantId), but who performs this task for the whole system. Use the Identity Manager Tenant application to create such a user:

In the system properties part of the docker-compose.yml

file

file, set the following (also needed for "scheduled cleaning" below):

Code Block

Code Block
# System user for scheduled tasks. Executes tasks relevant to ALL tenants. # Username cronUsername.encrypted=admin # Password cronPassword.encrypted=admin

Configure the SMTP server in Identity Manager. See Set up email template in Identity Manager.

Several attributes can be configured in the system properties part of the docker-compose.yml

file

file. Note that a property may span over several lines by ending intermediate lines with a backslash. At the very least, you must configure a recipient.
This is an example:

Code Blocktitle

System properties

Code Block

# When to execute. Fields: Seconds Minutes Hours Day-of-Month Month Day-of-Week Year(optional)
historyVerificationTrigger.cronExpression = 0 30 0 ? * SUN *

# Email address of users to be notified by scheduling jobs.
# Next line is mandatory!
#schedulingReporter.to =
#schedulingReporter.cc =
# Subject and contents of the mail to send on verification errors
historyVerificationJobDetail.jobDataMap[subject] = Error verifying object history signature
historyVerificationJobDetail.jobDataMap[text] = Hi there,\n\
something has gone wrong with the object history signature.\n\
For more details, please have a look at the server log.\n\
\n\

Also see "Define Cut-Off For Verification / Cleanup Window" below!

Expand

title	Multithreading

To increase performance, several threads are involved in the signature verification. The maximum number of threads can be configured by setting the system property commonHistoryService.signatureVerifyThreads which defaults to 30. If you experience issues with the responsiveness of the Identity Manager instance performing verification, consider lowering this value.

Delete old history entries

The periodically running running HistoryCleaningJob deletes deletes history entries that are no longer needed for verification in the current verification window, as defined by the configured cut-off (see below).

title

System property: Add user for scheduled task

Expand

title	Scheduled Cleaning

A scheduled job regularly cleans the signature chain of the object history.

As the object history signature spans over all history entries, regardless of the tenant, the cleaning on a multi tenant system should be done by a dedicated user that belongs to no tenant (that is, it has a null tenantId), but who performs this task for the whole system. Use the Identity Manager Tenant application to create such a user:

In the docker-compose.yml

file

file, set the following system property: (also needed "scheduled verification" above):

Code Block

Code Block
# System user for scheduled tasks. Executes tasks relevant to ALL tenants. # Username cronUsername.encrypted=admin # Password cronPassword.encrypted=admin

Several attributes can be configured with system properties. Note that a property may span over several lines by ending intermediate lines with a backslash.
This is an example of a configuration of the system property:

Code Blocktitle

Configure a system property for object history cleaning

Code Block
# When to execute. Fields: Seconds Minutes Hours Day-of-Month Month Day-of-Week Year(optional) historyCleaningTrigger.cronExpression = 0 30 0 ? * FRI *

Also see "Define Cut-Off For Verification / Cleanup Window" below.

Add system property

Expand

title	Delete history entries when deleting a core object

To be able to delete history entries when deleting a core object, you must add theobjectHistoryRemovalStrategy.removeWhenDeletingCoreObject property to the system properties part of the docker-compose.yml file file for Identity Manager Operator. This property is intentionally not provided by default.

Note
If you delete any history entries, the signature chain will be broken. This is not reversible.

Inthe system properties part of the docker-compose.yml

file
file, add the property below and set it to true:
code

title

Code Block
# Delete object history entries together with the entities objectHistoryRemovalStrategy.removeWhenDeletingCoreObject = true

Now the history entries will be deleted together with the core object itself.

Note
This feature only works for datapools with internal data sources, that is, internal table and lookup table.

Define cut-off for verification/cleanup window

Specify timeframe in system properties

Expand

title	Configure verification/deletion cut-off

By default the verification windows spans the entire history. You can limit it to the last N >= 12 months. This will enable deletion of older entries outside the verification window. Smaller values will be overridden by 12.

This will enable cleanup of older entries outside the verification window to reduce the amount of stored data.

Note
The cleanup process is irreversible, so be careful on how you configure the verification window before you run the deletion job for the first time!

If no cut-off is specified, the entire history is validated (default), and cleanup has no effect.

In the system properties part of the docker-compose.yml

file

file, enter this to specify a window starting 12 months in the past and ending at the current time:

Code Block

title

Code Block
# new parameter name in IDM 2204 (used to be "commonHistoryService.verificationIntervalMonths") commonHistoryService.historyCutOffDuration=12

Note that if a verification window is set, the following applies:

verification will fail if the oldest entry of any chain within the verification window points to a deleted predecessor
if verification fails for entries outside the verification window, this will be logged

Clustering

Expand

title	Clustering

In a clustered environment there is a separate chain per cluster node. With the default configuration, the chain's name is derived from the cluster node, that is, the jvmRoute attribute of the engine tag found in the server.xml. The implementation uses only the primary engine and does not support any special cases.

If there is a special cluster configuration, or if a cluster is not based on a unique jvmRoute per node, the attribute commonHistoryService.chainName needs to be provided. If this attribute is not found, like typically in single node environments, PRIME1 is used as default name.

Multitenancy

Expand

title	Multitenancy

Each history entry corresponds to an action that was performed on a core object in Identity Manager. Thus it belongs to a single tenant. The chained signature of the history on the other hand is global: there's exactly one chain for each cluster node, that spans over all history entries, regardless of the tenant. The signature ensures that no history entry of a Identity Manager cluster node has been manipulated.

For this reason it is recommended that the signature verification is performed by an administrator that is not bound to a tenant, that is, with an tenantId of null. The scheduled task that performs history verification should, in case of an error, be configured to send an email to a global user that administers Identity Manager for all tenants. It is still possible to verify the signatures with a user belonging to a tenant, but this should only be done on single tenant systems.

Logging

Expand

title	Logging

Validation can be time-consuming due to the cryptographic operations involved and the sheer amount of the ObjectHistory entries. Log messages provide insights and use the loglevel INFO for general information and ERROR for errors. Messages with a loglevel of DEBUG are logged for all validated entries.

title

Note

Viewing the messages at the DEBUG level

The DEBUG level is only recommended for debug purposes. It may severely impact performance by writing huge amounts of data to the logs.

The order of the validated entries may not match the chronological order of the entries, as multiple threads may validate the chain in parallel.

Every verification run has its own unique identifier that will be present in all its log entries. This can be used to filter the relevant log lines from a logfile. Detailed logs appear at the beginning and at the end of the validation of each chain as well as at the beginning and at the end of the complete validation. At fixed intervals of processed entries, a detailed log of the current state will be output.

Customize log level

To customize the log level, configure the logger de.vps.act.history.service as desired.

Configure the number of entries

To configure the number of entries, set the system property commonHistoryService.logInterval to the desired value. The default value is every 500.000 entries.

Additional information

Expand

title	Useful links

Versions Compared

Old Version 15

New Version 16

Key

Step-by-step instructions

Verify chained signature

Delete old history entries

Define cut-off for verification/cleanup window

Clustering

Multitenancy

Logging

Viewing the messages at the DEBUG level

Customize log level

Configure the number of entries

Additional information

Page Comparison

Versions Compared

Old Version 15

New Version 16

Key

Step-by-step instructions

Verify chained signature

Delete old history entries

Define cut-off for verification/cleanup window

Clustering

Multitenancy

Logging

Viewing the messages at the DEBUG level

Customize log level

Configure the number of entries

Additional information