Versions Compared

Version Old Version 27 New Version 28
Changes made by

David Banz

David Banz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

...

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

...

For development- and test-environments, the IDM bootstrap.zip package and bootstrap Docker container are provided to facilitate bootstrapping of all default descriptors with generated include a feature to generate test keys and certificates for all default descriptors.

Note

Using the dev/test bootstrapping tools on to generate keys and certificates for productive systems 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 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 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 pinBlob 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/ConfigZipEncrypter only.
Output format, currently always NX02.

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

If this is missing, a randomly generated IV will be used, which is the recommended behaviour.
Only for migrating EncryptedFields from SmartAct or ProAct it is necessary to set a fixed IV here.

...

Attribute of the type element inside key

Description

name

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

locationValue

  • For docker:

    • For a software keystore: place the keystore under docker/compose/certs before creating the container with docker compose. Then set its location as absolute path, prefixed with "classpath:" file: pointing to the mounted file in/certs,
      for example: locationValue="file:/certs/keystore.p12".
      Note: Default attestation keys referenced from the classpath, e.g. locationValue="classpath:keystoreattKeyMobileDef.p12" . Only if you need your own keys does this need to be changed.

    • 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/libpkcs11”libpkcs11"

  • 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="C:\Path\To\pkcs11_lib/usr/local/lib/libpkcs11"

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

In case of docker deployments pre-processing needs to be

See Scramble sensitive data in Identity Manager files for details.

...

  • use-case: Encrypt and decrypt fields in the Identity Manager database

  • included by default in XML config

  • placeholder keys forbidden for productive use due to loss of confidentiality

  • HSM supported for increased security

  • no versioning, always uses version 1

  • supported asymClipher values:

    • for HSM

      • RSA/ECB/OAEPWithSHA-384AndMGF1Padding

      • RSA/ECB/OAEPWithSHA-512AndMGF1Padding

    • for PKCS#12

      • RSA/None/OAEPWithSHA384AndMGF1Padding

      • RSA/None/OAEPWithSHA512AndMGF1Padding

      NOTE: you cannot reconfigure the asymCipher value after creation of encrypted fields, as decryption will then fail

  • key requirements:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

  • certificate requirements:

    • no special requirements, as only the key-pair is used

      • may be self-signed

      • key usage is not checked (recommended for informational purposes: set dataEncipherment)

      • validity is ignored

      • certificate does not need to be trusted

...