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
Optional: Sign and validate config zip files
Optional: Sign and encrypt emails
Encrypt communication with Hermod devices
Authenticate Smart ID Self-Service users to the Identity Manager backend

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.

Important info for customer deployments

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

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

Configuration file engineSignEncryptConfig.xml

Example configuration file

Example file engineSignEncryptConfig.xml

Example: engineSignEncryptConfig.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="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="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" size="" result="" key="signCertExpired" />
        </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="2048" result="" key="selfServiceJWTSignerCert" />
        </descriptor>
    </descriptors>
    <keys>
        <key name="encCert">
            <type name="pkcs12" locationValue="classpath:hybridEncKeypair.p12" pin="1234567"/>
        </key>
        <key name="configZipSignerCert">
            <type name="pkcs12" locationValue="classpath:sign.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:sign.p12" pin="1234"/>
        </key>
        <key name="signCertExpired">
            <type name="pkcs12" locationValue="classpath:sign_expired.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>
    </keys>
</engineSignEncrypt>

Predefined descriptors

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

Descriptor name	Description of use	Configurable?
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. Version must be "1".	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. If it is changed without using the Secret Fields Key Updater, then already encrypted fields stored in the database will not be readable.
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 can be used as with the ObjectHistorySigner descriptor, but this may make the file more difficult to read.
ObjectHistorySigner	Sign and verify database history.	Yes. Old descriptors and certificates must be kept by using versioning, in order to verify history entries signed with them.
SignEmailDescriptor	Sign emails from Identity Manager.	Yes. Changes take effect after restart of Identity Manager. Versioning can be used as with the SignEmailDescriptor descriptor, but this may make the file more difficult to read.
hermodDeviceEnc	Communication with new device via Smart ID Messaging (Hermod), for example with Smart ID Mobile App or Smart ID Desktop App. 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.	Yes. Changes take effect after restart of Identity Manager. Versioning can be used as with the hermodDeviceEnc descriptor, but this may make the file more difficult to read (and is also completely pointless in this particular case - see note to the left).
SelfServiceJWTSigner	Authenticate Smart ID Self-Service users to the Identity Manager backend.	Yes. Changes take effect after restart of Identity Manager. Versioning can be used as with the SelfServiceJWTSigner descriptor, but this may make the file more difficult to read.
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. These keys are used for validating the CSR that the "Mobile App: Create Key" task generates. See Smart ID Messaging - Standard service tasks in Identity Manager. att_ATTESTATION is the default key that will be used in case no other key has been configured. The key that is actually used can be configured in the "Mobile App: Create Key" task.	Yes. The default keys that are shipped with IDM are built into the 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. Changes take effect after restart of Identity Manager. Old descriptors and certificates can be kept by using versioning, in order to verify request signed with them.
att_FIXED	Validation of keys generated with the Smart ID Desktop App. This key is used for validating the CSR that the "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.	No. The Smart ID Desktop App currently does not support changing this key.

Descriptor

This is an example of a descriptor (taken from the file shown above in Example file engineSignEncryptConfig.xml), see the tables below the example for more information.

Descriptor example

<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: an asymmetric algorithm, for example, `RSA`. For signing: a signature or hashing algorithm to be used (for example, `SHA256withRSA` or `SHA-256`).
size	For field encryption: size of the symmetric key, for example, 256. For JWT: size of the asymmetric key, for example, 2048.
result	For field encryption: Output format. Currently, the only possible value is `NX02` : Output the raw bytes and some metadata.
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 Example file engineSignEncryptConfig.xml), see the tables below the example for more information.

Key example

<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 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: version control

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

Configure custom attestation keys

Custom attestation keys should be configured in IDM whenever possible. The Mobile and/or Desktop App must have access to the private keys. The corresponding public keys can be configured into IDM. This process consists of two steps:

Generate PKCS#12 keystores. Each PKCS#12 keystore must contain one certificate with the matching public key. We provide a tool that, given the modulus and public exponent of the public key in BASE64 format, creates the keystore. Just execute createP12.bat (windows) or createP12.sh (linux) and follow the instructions.
Configure the sign and encrypt engine. Copy the created keystore to an appropriate location and create a new key entry referencing it. Then create a new descriptor entry referencing the key entry. The name of the descriptor must be exactly the same as it is named in the Mobile or Personal App and furthermore prepended with the string "att_" in order for the relevant tasks to be able to find them. The engine configuration must be done on both the IDM Admin (for configuring the keys in the processses) and Operator (for the actual validation).

In order to use new keys for an existing descriptor, please create a new descriptor entry with an incremented version. Signatures will be validated against all versions of the key, until a valid one is found. This is useful in case some clients still have the old keys.

During bootstrap, if you have custom keys, it is advised to remove the default attestation keys from the engine's configuration. Thus only clients with the custom attestation keys will be able to generate keypairs. If instead you keep the default keys and add new keys under a newer version of the same descriptor, requests signed with the default keys will still be accepted!

A sample descriptor configuration looks like this:

Example: attestation key

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
         <descriptor name="att_ATTESTATION" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_old" />
        </descriptor>
          <descriptor name="att_ATTESTATION" version="2">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_current" />
        </descriptor>
    </descriptors>
    <keys>
        <key name="attestationKey_old">
            <type name="pkcs12" locationValue="classpath:attKeyOld.p12" pin="1234"/>
        </key>
         <key name="attestationKey_current">
            <type name="pkcs12" locationValue="classpath:attKeyCurrent.p12" pin="1234"/>
        </key>
     </keys>
</engineSignEncrypt>

This article includes updates for Smart ID 23.04.2.

Related information

Scramble sensitive data in Identity Manager files

Sign and encrypt engine in Identity Manager