Nexus Documentation
CURL vulnerability information (CVE-2023-38545) - Nexus awareness advisory on Microsoft's update KB5014754

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 61 Next »

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

IDM 24.R1 makes a number of significant changes compared to earlier releases!
Please review this document and its related pages carefully before proceeding with a fresh installation or upgrade.

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 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 (always supported).

Structure Of The Configuration File

Below is an example of the XML configuration. On 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 Admin and IDM Operator.
There are also several tools including a similar configuration file.

<?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" key="configZipEncrypterCert"
                  asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
        </descriptor>
        <descriptor name="ConfigZipSigner" version="1">
            <type algorithm="SHA-256" key="configZipSignerCert" />
        </descriptor>
        <descriptor name="ObjectHistorySigner" version="1">
            <type algorithm="SHA-256" key="objectHistorySignerCert" />
        </descriptor>
        <descriptor name="SignEmailDescriptor" version="1">
            <type algorithm="SHA256withRSA" key="emailSigningCert" />
        </descriptor>
        <descriptor name="hermodDeviceEnc" version="1">
            <type algorithm="SHA256withRSA" key="serverCert" />
        </descriptor>
        <descriptor name="SelfServiceJWTSigner" version="1">
            <type algorithm="RSA" key="selfServiceJWTSignerCert" />
        </descriptor>
        <descriptor name="ContentProviderJWSSigner" version="1">
            <type algorithm="RSA" key="contentProviderJWSSignerCert" />
        </descriptor>
        <descriptor name="att_external-attestation-1" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_1" />
        </descriptor>
        <descriptor name="att_external-attestation-2" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_2" />
        </descriptor>
        <descriptor name="att_external-attestation-3" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_3" />
        </descriptor>
        <descriptor name="att_external-attestation-4" version="1">
            <type algorithm="SHA256withRSA" key="attestationKey_mobile_4" />
        </descriptor>
        <descriptor name="att_ATTESTATION" version="1">
            <type algorithm="SHA256withRSA" 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>

The configuration is divided into entries for descriptors and keys, with each descriptor referencing one of the key-entries.

Descriptor Naming

IDM references descriptors by their name. Some names are fixed (e.g. ConfigZipEncrypter is always used for encrypting configuration files), some can be named arbitrarily (e.g. descriptors for PIN blob decryption).

Descriptor Versioning

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:

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

Bootstrapping Requirements

Important: Most descriptors need to have their certificates and keys bootstrapped before starting the application(s) for the first time.

IDM 24.R1 makes a number of significant changes:

  • PKCS#12 files containing demo keys are no longer included to avoid them ending up in productive environments.

  • Various checks are introduced - see Sign and Encrypt engine bootstrap verification:

    • The old demo keys are explicitly blacklisted and IDM will print an error log message, if any of those is encountered on startup of IDM Operator and IDM Admin.

    • IDM Admin and IDM Operator will no longer start without bootstrapping, as most descriptors have missing keys/certs by default.

    • IDM Admin and IDM Operator check on startup whether the configured key for encrypted fields matches the database and will abort if that is not the case.

    • IDM Operator checks on startup if the currently configured key for history signing matches the database and will abort if that is not the case.

  • Bootstrap CA/certificate/key generation tooling has been refined, it now works properly on Docker and is limited to dev-/test-use (see Bootstrapping Development And Test Systems).
    For productive environments manual bootstrapping via Certificate Authorities is required - see Bootstrap the sign and encrypt engine in Identity Manager for details.

  • Pin scrambling of signencrypt.xml now works in Docker deployments via dedicated tooling. See Scramble sensitive data in Identity Manager files.

  • Each descriptor now references its own key by default, instead of e.g. ZIP signing and history signing sharing the same key.

Whenever object history entries or secrets were created with the demo keys, a simple bootstrapping is no longer possible without resigning the object history (using the batch_re-sign_history tool) and re-encrypting the secrets (using the batch_secretfieldstore_change_encryption_key tool, see Change Encryption key of secret field store).

Bootstrapping Productive Systems

Bootstrapping of productive systems involves use of various certificate authorities to generate keys and issue certificates used by IDM.

Most descriptors, such as EncryptedFields and ObjectHistorySigner, always require proper bootstrapping for secure operation. However, depending on the subset of IDM features to be used, certain descriptors may be configured with placeholder keys and certificates (e.g. SignEmailDescriptor, if E-Mail signing in IDM is not enabled).

See Bootstrap the sign and encrypt engine in Identity Manager detailing the specific requirements for each descriptor.

Bootstrapping Dev/Test Systems

For development- and test-environments, test keys and certificates for all default descriptors can be generated using features of the IDM bootstrap.zip package and bootstrap Docker container, see Bootstrapping Development And Test Systems .

Do not use the bootstrapping tools to generate keys and certificates for productive systems as this is a security risk!

XML Elements

Descriptor

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

Descriptor example

<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

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

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: 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,
      for example: locationValue="file:/certs/keystore.p12".
      Note: Default attestation keys are referenced from the classpath, e.g. 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="/usr/local/lib/libpkcs11hsm"

pin

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.

Additional Information



  • No labels

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions