Info
This article is valid for Smart ID Identity Manager 24.R1 or later.

This article describes the sign and encrypt engine in Smart ID Identity Manager. There are a number of use cases in Identity Manager that are based on encryption or signing, for example:

Encrypt and decrypt fields in the Identity Manager database
Sign and verify object history
Sign and validate config zip files
Encrypt config zip files
Sign and encrypt emails
Create device encryption certificates used in certain Hermod scenarios
Authenticate Smart ID Self-Service users to the Identity Manager backend
Creating JWS signatures used for Hermod's content provider API
Decrypting PIN blobs from pre-personalized smart-cards created with Personal Desktop Client
Attestation for provisioning to Smart ID Mobile / Desktop Apps

The sign and encrypt engine provides a consistent configuration of certificates for both signing and encryption. You can define algorithms and parameters and reference keys from an HSM or from PKCS#12 files.

The issuers of the referenced keys should also be trusted, that is, their certificates must be in the configured truststore. The default keystore location is <tomcat>/conf/prime.truststore, however a different location may be set in <tomcat>/webapps/<application>/WEB-INF/classes/system.properties under the key jksKeyStoreProvider.keyStorePath.

Note

Important info for customer deployments

Several supplied P12 files in Identity Manager modules.zip package, such as sign.p12, are merely examples and must be replaced for customer deployments.

Since IDM 24.R1 those files are no longer shipped in WAR files and Docker images, making proper bootstrapping mandatory.

You can also find useful information here: Change Encryption key of secret field store.

Configuration file engineSignEncryptConfig.xml

Example file: engineSignEncryptConfig.xml

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
        <descriptor name="EncryptedFields" version="1">
            <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="encCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
        </descriptor>
        <descriptor name="ConfigZipEncrypter" version="1">
            <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="configZipEncrypterCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
        </descriptor>
        <descriptor name="ConfigZipSigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="configZipSignerCert" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="2">
            <type algorithm="SHA-256" size="" result="" key="objectHistorySignerCert" />
        </descriptor>
        <descriptor name="SignEmailDescriptor" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="emailSigningCert" />
        </descriptor>
        <descriptor name="hermodDeviceEnc" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="serverCert" />
        </descriptor>
        <descriptor name="SelfServiceJWTSigner" version="1">
            <type algorithm="RSA" size="" result="" key="selfServiceJWTSignerCert" />
        </descriptor>
        <descriptor name="ContentProviderJWSSigner" version="1">
            <type algorithm="RSA" size="" result="" key="contentProviderJWSSignerCert" />
        </descriptor>
        <descriptor name="att_external-attestation-1" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_mobile_1" />
        </descriptor>
        <descriptor name="att_external-attestation-2" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_mobile_2" />
        </descriptor>
        <descriptor name="att_external-attestation-3" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_mobile_3" />
        </descriptor>
        <descriptor name="att_external-attestation-4" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_mobile_4" />
        </descriptor>
        <descriptor name="att_ATTESTATION" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_mobile_pda_def" />
        </descriptor>
    </descriptors>
    <keys>
        <key name="encCert">
            <type name="pkcs12" locationValue="classpath:hybridEncKeypair.p12" pin="1234"/>
        </key>
        <key name="configZipEncrypterCert">
            <type name="pkcs12" locationValue="classpath:encryptConfig.p12" pin="1234"/>
        </key>
        <key name="configZipSignerCert">
            <type name="pkcs12" locationValue="classpath:signConfig.p12" pin="1234"/>
        </key>
        <key name="objectHistorySignerCert">
            <type name="pkcs12" locationValue="classpath:sign.p12" pin="1234"/>
        </key>
        <key name="selfServiceJWTSignerCert">
            <type name="pkcs12" locationValue="classpath:signJWT.p12" pin="1234"/>
        </key>
        <key name="contentProviderJWSSignerCert">
            <type name="pkcs12" locationValue="classpath:signJWS.p12" pin="1234"/>
        </key>
        <key name="emailSigningCert">
            <type name="pkcs12" locationValue="classpath:emailSigning.p12" pin="1234"/>
        </key>
        <key name="serverCert">
            <type name="pkcs12" locationValue="classpath:deviceEncCA.p12" pin="1234"/>
        </key>
        <key name="attestationKey_mobile_1">
            <type name="pkcs12" locationValue="classpath:attKeyMobile1.p12" pin="936584967"/>
        </key>
        <key name="attestationKey_mobile_2">
            <type name="pkcs12" locationValue="classpath:attKeyMobile2.p12" pin="873145568"/>
        </key>
        <key name="attestationKey_mobile_3">
            <type name="pkcs12" locationValue="classpath:attKeyMobile3.p12" pin="8564789632"/>
        </key>
        <key name="attestationKey_mobile_4">
            <type name="pkcs12" locationValue="classpath:attKeyMobile4.p12" pin="9263564893"/>
        </key>
        <key name="attestationKey_mobile_pda_def">
            <type name="pkcs12" locationValue="classpath:attKeyMobileDef.p12" pin="2586453793"/>
        </key>
    </keys>
</engineSignEncrypt>

Predefined descriptors

The following descriptors are predefined in the default file engineSignEncryptConfig.xml:

...

Descriptor name

...

Description of use

...

Configurable?

...

HSM supported

...

EncryptedFields

...

Encrypt secret fields in Identity Manager, for example PIN codes in data pool definitions. It is not possible to change the keys once encrypted fields have been stored in the database.

Yes.

The descriptor can be changed during installation. After installation, it can only be changed using the Secret Fields Key Updater. See Change Encryption key of secret field store.

...

ConfigZipEncrypter

...

Encrypt configuration ZIP files downloaded from IDM.

...

Yes.

Note

If it is changed, then existing encrypted config ZIP files can lo longer be imported.

Note that it is currently limited to a single descriptor version (defaults to 1 in the bean config).

...

ConfigZipSigner

...

Sign the Identity Manager configuration archive. Verification of the configuration archive uses the certificate that was put in the archive during signing.

...

Yes.

Changes take effect after restart of Identity Manager.

Versioning is possible, but unnecessary.

It is sufficient that the certificate that signed the old configs is trusted via the IDM truststore.

...

ObjectHistorySigner

...

Sign and verify database history.

Yes.

Note
Old descriptors and certificates must be kept by using versioning, in order to verify history entries signed with them (see above example file).

...

SignEmailDescriptor

...

Sign emails from Identity Manager.

...

Yes.

Changes take effect after restart of Identity Manager.

Versioning is possible, but unnecessary.

...

hermodDeviceEnc

Communication with new device via Smart ID Messaging (Hermod), for example with Smart ID Mobile App or Smart ID Desktop App.

Note
Unlike the other entries, this one has no security relevance! What is configured here is a dummy CA that issues transient certificates which are merely used internally as a form of transport container for the keyUsage attribute.

...

Yes.

Changes take effect after restart of Identity Manager.

Versioning is possible, but unnecessary.

...

(not needed, though)

...

SelfServiceJWTSigner

...

Authenticate Smart ID Self-Service users to the Identity Manager backend.

...

Yes.

Changes take effect after restart of Identity Manager

Versioning is possible, but unnecessary.

...

ContentProviderJWSSigner

...

Used for JWS signing in Hermod Content Provider API.

...

Yes.

Versioning is possible, but unnecessary.

...

att_ATTESTATION,

att_external-attestation-1,

att_external-attestation-2,

att_external-attestation-3,

att_external-attestation-4

...

Validation of keys generated with the Smart ID Mobile App and Smart ID Desktop App.

These keys are used for validating the CSR that the "Mobile App: Create Key", "Desktop App: Create Virtual Smart Card Key" and "Desktop App: Create Windows Cert Store Key" tasks generate. See Smart ID Messaging - Standard service tasks in Identity Manager and Smart ID Messaging - Standard service tasks in Identity Manager. In these tasks you can configure which key to use:

att_ATTESTATION is the default key that will be used in case no other key has been configured.
att_external_attestation-1 through att_external_attestation-4 are further keys that are available on the Mobile App only.

No, for the Smart ID Desktop App, as The Smart ID Desktop App currently does not support changing this key.

Yes, for Smart ID Mobile App.

The default keys that are shipped with Identity Manager are built into Smart ID Mobile App. In case the mobile app is provided with custom keys, you need to create PKCS#12 containers with these keys and configure them in the engine (see https://doc.nexusgroup.com/pub/configure-custom-attestation-keys for now to create PKCS#12 containers from the public key).

You can also export the certificates from the PKCS#12 containers the import them into an HSM.

Changes take effect after restart of Identity Manager.

Note
Old descriptors and certificates can be kept by using versioning, in order to verify requests signed with them.

...

(but less relevant, as IDM only needs the public keys)

Descriptor

...

Descriptor example

Code Block
<descriptor name="ObjectHistorySigner" version="2"> <type algorithm="SHA-256" size="" result="" key="objectHistorySignerCert" /> </descriptor>

`descriptor` element attribute	Description
name	Used by Identity Manager to refer to this descriptor. There might be different descriptors with the same name but with different versions.
version	A numeric value that denotes the descriptor's version. This is only needed for the ObjectHistorySigner. A new version of a descriptor is needed, for example, when an old certificate needs to be replaced. The descriptor with the highest version number is used. Verification of Object History entries will automatically select the right descriptor version.

...

Attribute of the type element inside descriptor

...

Description

...

algorithm

...

For field encryption: a symmetric algorithm to be used, for example, AES/CBC/PKCS7Padding.

For JWT/JWS: only RSA.

For zip/history signing: hashing algorithm to be used (for example, SHA-256).

For mail signing/hermod: a signature or hashing algorithm to be used (for example, SHA256withRSA).

...

size

...

For field encryption: size of the symmetric key, for example, 256.

...

result

For field encryption: Output format. Currently, the only possible value is

...

key

...

Refers to a key defined in the same document

...

asymCipher

...

For field encryption: specific cipher description, for example, RSA/None/OAEPWithSHA384AndMGF1Padding.

When used with an HSM, you need to adjust the cipher format to be compatible with the JCE provider used for HSM access.
For example, instead of the above cipher description, specify RSA/ECB/OAEPWithSHA-384AndMGF1Padding (ECB instead of None and SHA-384 instead of SHA384).

...

initVector

...

If this is missing, a random generated IV will be used. This is the recommended behaviour.

For migrating SmartAct or ProAct it is necessary to set a fixed IV here.

Key

This is an example of a key (taken from the file shown above in the example file engineSignEncryptConfig.xml or signencrypt.xml for docker deployment), see the tables below the example for more information.

Key example

Code Block
<key name="objectHistorySignerCert"> <type name="pkcs12" locationValue="classpath:sign.p12" pin="1234"/> </key>

`key` element attribute	Description
name	Used by descriptors' key attribute to reference this key.

...

Attribute of the type element inside key

...

Description

...

name

...

Type of storage. For example, pkcs12 and HSM are supported.

...

locationValue

For docker:

...

locationValue="classpath:keystore.p12"

...

For WAR file deployment:

For a software keystore: place the keystore under web-inf/classes and set its location, prefixed with "classpath:", for example:

locationValue="classpath:keystore.p12"

For an HSM, use the filename of the PKCS11 library, without filename extension, for example,

locationValue="C:\Path\To\pkcs11_lib"

...

PIN for the keystore or HSM.

To avoid having clear text PINs in this file, the pin should be scrambled. That can be achieved by setting it with

pin.encrypted="1234"

instead of

pin="1234"

See Scramble sensitive data in Identity Manager files for details.

Configure ObjectHistorySigner

Identity Manager needs access to the old descriptors and certificates in order to verify history entries signed with them. To make a change:

Create a new descriptor with the same name but increase its version number.
To use a new PKCS#12 container, create a new key entry with a unique name and reference it using the key attribute of the new descriptor.

Identity Manager will now use the new descriptor for signing future entries. Verification will automatically use the correct descriptor, that is, older entries will use the old descriptor(s) while new ones will use the new one.

This is an example where the PKCS#12 container is changed.

Example: versioning

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
        <descriptor name="ObjectHistorySigner" version="2">
            <type algorithm="SHA-256" size="" result="" key="signCertV2" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="signCertV1" />
        </descriptor>
      </descriptors>
    <keys>
        <key name="signCertV2">
            <type name="pkcs12" locationValue="classpath:sign.p12" pin.encrypted="1234" />
        </key>
        <key name="signCertV1">
            <type name="pkcs12" locationValue="classpath:sign_expired.p12" pin="encrypted:h1AKH0MeF1mOUSW1s+9vN+MAeA=="/>
        </key>       
    </keys>
</engineSignEncrypt>

Additional information

Smart ID Identity Manager

Configure HSM in

Expand

title	Useful links

Info

This article includes updates for Identity Manager 5.0.1.

Note

Before installing or upgrading

Read this article and its related pages before you proceed with a fresh installation or upgrade since the Identity Manager 5.0.1 release comes with significant changes compared to earlier versions.

Note

Important information

Most descriptors must have their certificates and keys bootstrapped before starting the application(s) for the first time.

Sign and encrypt engine

The sign and encrypt engine is the central component of Identity Manager for signing, verification, and encryption using keys and certificates. It handles several use cases, like encryption and decryption of fields in the Identity Manager database, signing, verification, and encryption of the object history and more.

Most use cases have to be configured for each deployment, so that the private keys are kept secret. The sign and encrypt engine provides a consistent configuration of keys and certificates for both signing and encryption. You can define algorithms and parameters and reference keys from an HSM (for most use cases) or from PKCS#12 files (for all use cases).

Additional Information

Expand

title	Useful links

Child pages (Children Display)

all	true
depth	0
allChildren	true
style
sortAndReverse
first	0

...

Version	Old Version 19	New Version Current
Changes made by	David Banz	Ylva Andersson
Saved on	Apr 03, 2024	Dec 02, 2024

Page Comparison

Versions Compared

Key

Important info for customer deployments

Configuration file engineSignEncryptConfig.xml

Example file: engineSignEncryptConfig.xml

Predefined descriptors

Descriptor

Descriptor example

Key

Key example

Configure ObjectHistorySigner

Example: versioning

Additional information

Before installing or upgrading

Important information

Sign and encrypt engine

Additional Information