...

Info
This article is new for Identity Manager 5.0.1.

The sign and encrypt engine has one configuration file. On Docker docker deployments it is located in docker/compose/identitymanager/config/signencrypt.xml, on WAR deployments it is located in WEB-INF/classes/engineSignEncryptConfig.xml of IDM Identity Manager Admin and IDM Identity Manager Operator.
There are also several tools including a similar configuration file.

...

The configuration is divided into entries for descriptors and keys. Each descriptor handles one distinct use case and uses one of the key-entries.

...

Descriptors

IDM Identity Manager references descriptors by their name: for each use case there is a known descriptor name. Most names are fixed (e.g. for example, ConfigZipEncrypter is always used for encrypting configuration files) and a few can be named arbitrarily (e.g. for example, descriptors for PIN blob decryption).

Descriptor

...

Some descriptors support multiple versions. For example, you can replace the key of the ObjectHistorySigner by adding a descriptor of this name with a newer version, and leaving the existing descriptor with the old version configured. This will cause any new signatures to be created with the new key, but you can still verify signatures made with the old one.

See the following example:

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
        <descriptor name="ObjectHistorySigner" version="2">
            <type algorithm="SHA-256" key="newHistorySigner" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" key="oldHistorySigner" />
        </descriptor>       
        <!-- others descriptors -->
    </descriptors>
    <keys>
        <key name="newHistorySigner">
            <type name="pkcs12" locationValue="classpath:sign_new.p12" pin="1234"/>
        </key>
        <key name="oldHistorySigner">
            <type name="pkcs12" locationValue="classpath:sign_old.p12" pin="1234"/>
        </key>
        <!-- other keys -->
    </keys>
</engineSignEncrypt>

There are also descriptors which cannot be versioned, e.g. EncryptedFields. For those the version always needs to be set to 1.

Descriptor

See the tables below the example for more information on the different possible attributes of a descriptor/-type.

Descriptor example

Code Block

language	xml

<descriptor name="ObjectHistorySigner" version="1">
    <type algorithm="SHA-256" 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 key 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 EncryptedFields/ConfigZipEncrypter: symmetric algorithm to be used, usually AES/CBC/PKCS7Padding.

For SelfServiceJWTSigner/ContentProviderJWSSigner: always RSA.

For ConfigZipSigner/ObjectHistorySigner: hashing algorithm to be used (for example, SHA-256).

For SignEmailDescriptor/hermodDeviceEnc/att_* and pin-blob decryption descriptors:
signature algorithm to be used (for example, SHA256withRSA).

For idopteAuthentication: always NoneWithRSA.

...

size

...

For EncryptedFields/ConfigZipEncrypter only.
Size of the symmetric key, either 128or 256 (recommended).

...

result

...

For EncryptedFields only.
Output format, currently always NX02.

...

key

...

The descriptor’s key. Refers to a key defined in the same document.

...

asymCipher

...

For EncryptedFields/ConfigZipEncrypter only.
Cipher definition, e.g. 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 definition, specify RSA/ECB/OAEPWithSHA-384AndMGF1Padding
(ECBinstead of Noneand SHA-384 instead of SHA384).

...

initVector

...

Only needed for migrating EncryptedFields from SmartAct or ProAct. A fixed Initialization Vector (IV).

For other descriptors, omit this attribute in order to use randomly generated IVs.

Key

...

example

Code Block

language	xml

<descriptor name="ObjectHistorySigner" version="1">
    <type algorithm="SHA-256" key="objectHistorySignerCert" />
</descriptor>

See the following tables for more information on the different possible attributes of a descriptor/-type.

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 key 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 `EncryptedFields`/`ConfigZipEncrypter`: symmetric algorithm to be used, usually `AES/CBC/PKCS7Padding`. For `SelfServiceJWTSigner`/`ContentProviderJWSSigner`: always `RSA`. For `ConfigZipSigner`/`ObjectHistorySigner`: hashing algorithm to be used (for example, `SHA-256`). For `SignEmailDescriptor`/`hermodDeviceEnc`/`att_*` and pin-blob decryption descriptors: signature algorithm to be used (for example, `SHA256withRSA`). For `idopteAuthentication`: always `NoneWithRSA`.
size	For `EncryptedFields`/`ConfigZipEncrypter` only. Size of the symmetric key, either `128`or `256` (recommended).
result	For `EncryptedFields` only. Output format, currently always `NX02`.
key	The descriptor’s key. Refers to a key defined in the same document.
asymCipher	For `EncryptedFields`/`ConfigZipEncrypter` only. Cipher definition, 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 definition, specify `RSA/ECB/OAEPWithSHA-384AndMGF1Padding` (`ECB`instead of `None`and `SHA-384` instead of `SHA384`).
initVector	Only needed for migrating `EncryptedFields` from SmartAct or ProAct: a fixed Initialization Vector (IV). For other descriptors, omit this attribute in order to use randomly generated IVs.

Descriptor versioning

The ObjectHistorySigner supports multiple versions. You can replace its key by adding a descriptor with the same name and a newer version, and leaving the existing descriptor with the old version configured. This will cause any new signatures to be created with the new key, but you can still verify signatures made with the old one.

Expand

title	Example

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
        <descriptor name="ObjectHistorySigner" version="2">
            <type algorithm="SHA-256" key="newKey" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" key="oldKey" />
        </descriptor>       
        <!-- others descriptors -->
    </descriptors>
    <keys>
        <key name="newKey">
            <type name="pkcs12" locationValue="classpath:sign_new.p12" pin="1234"/>
        </key>
        <key name="oldKey">
            <type name="pkcs12" locationValue="classpath:sign_old.p12" pin="1234"/>
        </key>
        <!-- other keys -->
    </keys>
</engineSignEncrypt>

There are also descriptors which cannot be versioned, for example, EncryptedFields. For those the version always must be set to 1.

Currently most descriptors either do not support versioning at all or do not benefit from defining multiple versions.

Key

Key elements are referenced by the descriptors. They describe keys found in HSMs and/or keystores. Each key should be used by only one descriptor.

Key example

Code Block

language	xml

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

See the tables below for more information about the key/-type.

`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: pkcs12or HSM.

locationValue

For docker:

For a software keystore (pkcs12): place the keystore under docker/compose/certs before creating the container with docker compose. Then set its location as absolute path, prefixed with file: pointing to the mounted file in/certs (inside the container),

for example: locationValue="file:/certs/keystore.p12".

Note:

Default attestation keys are referenced from the classpath

, e.g.

, for example, locationValue="classpath:attKeyMobileDef.p12". Change this only if you need your own keys.

For an HSM: ensure the PKCS11 library is mounted into the container, then use the container’s path of the PKCS11 library, without filename extension, for example: locationValue="/usr/local/lib/libpkcs11hsm"

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 path of the PKCS11 library, without filename extension, for example: locationValue="

classpath:keystore.p12"

For an HSM: use the path of the PKCS11 library, without filename extension,
for example: locationValue="/usr/local/lib/libpkcs11hsm"

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".

For WAR deployments the pin will then be scrambled on the next (re-)start of Tomcat.

For Docker deployments you need to scramble the pins with a dedicated tool while IDM Admin / IDM Operator containers are not running.
See Scramble sensitive data in Identity Manager files for detailed instructions.

Example configuration file

Below is an example of the XML configuration.

...

language	xml

...

/usr/local/lib/libpkcs11hsm"

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".

For WAR deployments the pin will then be scrambled on the next (re-)start of Tomcat.

For docker deployments you need to scramble the pins with a dedicated tool while Identity Manager Admin/Identity Manager Operator containers are not running.

After scrambling, the PIN will look something like pin="encrypted:someBase64EncodedValue". See Scramble sensitive data in Identity Manager files for detailed instructions.

Configuration file example

Expand

title	Example of a typical configuration file

Code Block

language	xml

<?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="

EncryptedFields

ConfigZipEncrypter" version="1">
            <type algorithm="AES/CBC/PKCS7Padding" size="256

" result="NX02

" key="

encCert

configZipEncrypterCert"

asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
        </descriptor>
        <descriptor name="

ConfigZipEncrypter

ConfigZipSigner" version="1">
            <type algorithm="

AES/CBC/PKCS7Padding" size="

SHA-256" key="

configZipEncrypterCert"

configZipSignerCert" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type

asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"

algorithm="SHA-256" key="objectHistorySignerCert" />
        </descriptor>
        <descriptor name="

ConfigZipSigner

ObjectHistorySigner" version="

1

2">
            <type algorithm="SHA-256" key="

configZipSignerCert

newObjectHistorySignerCert" />
        </descriptor>
        <descriptor name="

ObjectHistorySigner

SignEmailDescriptor" version="1">
            <type algorithm="

SHA-256

SHA256withRSA" key="

objectHistorySignerCert

emailSigningCert" />
        </descriptor>
        <descriptor name="

SignEmailDescriptor

hermodDeviceEnc" version="1">
            <type algorithm="SHA256withRSA" key="

emailSigningCert

serverCert" />
        </descriptor>
        <descriptor name="

hermodDeviceEnc

SelfServiceJWTSigner" version="1">
            <type algorithm="

SHA256withRSA

RSA" key="

serverCert

selfServiceJWTSignerCert" />
        </descriptor>
        <descriptor name="

SelfServiceJWTSigner

ContentProviderJWSSigner" version="1">
            <type algorithm="RSA" key="

selfServiceJWTSignerCert

contentProviderJWSSignerCert" />
        </descriptor>
        <descriptor name="

ContentProviderJWSSigner

att_external-attestation-1" version="1">
            <type algorithm="

RSA

SHA256withRSA" key="

contentProviderJWSSignerCert

attestationKey_mobile_1" />
        </descriptor>
        <descriptor name="att_external-attestation-

1

2" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_

1

2" />
        </descriptor>
        <descriptor name="att_external-attestation-

2

3" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_

2

3" />
        </descriptor>
        <descriptor name="att_external-attestation-

3

4" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_

3

4" />
        </descriptor>
        <descriptor name="att_

external-attestation-4

ATTESTATION" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_pda_

4

def" />
        </descriptor>
    </descriptors>
    <keys>

<descriptor

<key name="

att_ATTESTATION" version="1

encCert">
            <type

algorithm

name="pkcs12" locationValue="

SHA256withRSA

classpath:hybridEncKeypair.p12"

key="attestationKey_mobile_pda_def"

pin="encrypted:UPYN6QD/Vd45fbrQ/QF2DrYlRbaBOvriXkD3OxWLetgiXbQ="/>
        </

descriptor> </descriptors> <keys>

key>
        <key name="

encCert

configZipEncrypterCert">
            <type name="pkcs12" locationValue="classpath:

hybridEncKeypair

encryptConfig.p12" pin="

1234

encrypted:waKnF9aR6YCwamkL5/aKfVk3A1YjZbApclCpwmRuScmSfm0="/>
        </key>
        <key name="

configZipEncrypterCert

configZipSignerCert">
            <type name="pkcs12" locationValue="classpath:

encryptConfig

signConfig.p12" pin="

1234

encrypted://1p2CV3vDLvjyCuQKj4Zg2gSJGNhJ3R5qfgPKnqoyVwhGA="/>
        </key>
        <key name="

configZipSignerCert

newObjectHistorySignerCert">
            <type name="pkcs12" locationValue="classpath:

signConfig

historySignNew.p12" pin="

1234

encrypted:RC1w/BVMH1bwgM4DGKUeMvxIYonTKXrPa/sKr+JFbWgd/4o="/>
        </key>
        <key name="objectHistorySignerCert">
            <type name="pkcs12" locationValue="classpath:

sign

historySign.p12" pin="

1234

encrypted:nr7t9dSRu21RWpc95C6/JyczKI2wMkOo+93JLy7da/jkg7E="/>
        </key>
        <key name="selfServiceJWTSignerCert">
            <type name="pkcs12" locationValue="classpath:signJWT.p12" pin="

1234

encrypted:8ri1LiK3J8Ur8F1wSw0Qa/UYDoaJjo85I4QZC9mX9f/H7zc="/>
        </key>
        <key name="contentProviderJWSSignerCert">
            <type name="pkcs12" locationValue="classpath:signJWS.p12" pin="

1234

encrypted:4Kj0VidwLlISBKXAFZ+ZorOjL4HK6c86zESBaeoPWJ6oEcI="/>
        </key>
        <key name="emailSigningCert">
            <type name="pkcs12" locationValue="classpath:emailSigning.p12" pin="

1234

encrypted:mwd15YNfR2LyUaLtoCIO9R0fGvd3O2z7kfaYw2ObSqsigtA="/>
        </key>
        <key name="serverCert">
            <type name="pkcs12" locationValue="classpath:deviceEncCA.p12" pin="

1234

encrypted:yZJ7NcLs82mSs/nmV0s83c/sjvDA1kXspYWjvD3D7KsAS/c="/>
        </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>

Version	Old Version 7	New Version Current
Changes made by	Paul Zachos	Ylva Andersson
Saved on	Apr 16, 2024	Dec 02, 2024

Page Comparison

Versions Compared

Key

Descriptors

Descriptor

Descriptor

Key

example

Descriptor versioning

Key

Key example

Example configuration file

Configuration file example