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

TODO: Boostrapping Migration Docs for Upgrade

Bootstrapping Productive Systems

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

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.

See Detailed Overview Of Descriptors below detailing the specific requirements for each descriptor.

Bootstrapping Dev/Test Systems

For development- and test-environments, the IDM bootstrap.zip package and bootstrap Docker container include a feature to generate test keys and certificates for all default descriptors.

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

...

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.

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: 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 referenced from the classpath, e.g. locationValue="classpath:attKeyMobileDef.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/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.

Detailed Overview Of Descriptors

The following lists detailed requirements for how each descriptor shall be bootstrapped on a productive system, as well as the risks associated with failing to do so properly.

EncryptedFields

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

• configured in these applications

  • Identity Manager Admin (previously know as PRIME Designer)

  • Identity Manager Operator (previously known as PRIME Explorer)

• configured in these special-case tools

  • batch_secretfieldstore_change_encryption_key

    (repair tool for secret fields)

  • batch_migration_smartact_to_prime

    (for migration of data from Identity Manager's/PRIME's predecessor SmartAct, it has additional requirements for decrypting secret fields and config entries from the source system)

• placeholder keys forbidden for productive use

  • loss of confidentiality

  • the key can only be changed with the tool batch_secretfieldstore_change_encryption_key once the first secret is stored in the database

• storage: pkcs12, HSM (recommended)

• versioning: not supported, 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

• supported keys:

  • 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

ConfigZipEncrypter

• storage: pkcs12, HSM (recommended)

• no versioning, always uses version 1

• placeholder P12 is allowed only if zip encryption is disabled

• supported asymClipher values:

  • for HSM

    • RSA/ECB/OAEPWithSHA-384AndMGF1Padding

    • RSA/ECB/OAEPWithSHA-512AndMGF1Padding

  • for PKCS#12

    • RSA/None/OAEPWithSHA384AndMGF1Padding

    • RSA/None/OAEPWithSHA512AndMGF1Padding

  • NOTE: but you cannot reconfigure the asymCipher after exporting an encrypted ZIP, as config import of such a ZIP will 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 + keyEncipherment )

    • validity is ignored

    • certificate does not need to be trusted

ConfigZipSigner

• storage: pkcs12, HSM (recommended)

• placeholder P12 is allowed if zip signing+verification is disabled

• Versioning is possible, but unnecessary. It is sufficient that the certificate that signed the old configs is trusted via the IDM truststore.    

• must NOT be self-signed!

• key usage: digitalSignature MUST be present if KeyUsage is critical (explicit check in our code!, Signer.java)

• issuing CA cert MUST be in IDM truststore

• issues if not configured as above:
  export is blocked unless "zipPacker.signZip=false"
  verification does not work, ZIP appears unsigned

• key type: RSA-2048 and up (4096 recommended), no ECC support!

• digest: SHA-256
        (selecting SHA-38 or SHA-512 only affects MANIFEST.MF, other parts use SHA-256 always)

• validity: at your discretion, but bear in mind... 

  • if expired, export is blocked unless "zipPacker.signZip=false"

  • if expired on upload: "Verification failed. The certificate has expired."

ObjectHistorySigner

• included by default in config XML

• storage: pkcs12, HSM (recommended)

• NEVER placeholder cert!

• tooling needed to fix if initially wrong key

• versioning supported

• key usage: digitalSignature MUST be present if KeyUsage is critical (explicit check in our code and JRE code, Signer.java, Signature.java)

• trust does not matter

• MAY be self-signed

• key type: RSA-2048 and up (4096 recommended), no ECC support!

• digest: SHA-256, SHA-384, SHA-512
  WARNING! changing the digest after history entries have been written requires a new version of the descriptor!
        IDM startup will fail otherwise!

• algorithm cannot be changed after the fact - deployment will break!

• validity: does not matter, still works when expired

SignEmailDescriptor

• storage: pkcs12, HSM (recommended)

• placeholder P12 is allowed if email signing is not used

• must NOT be self-signed!

• versioning possible, but unnecessary

• RFC says: proper S/MIME cert with correct sender e-mail configured in subject DN's E field and/or SAN RFC-822
      (if subject DN email field is absent, SAN must be critical),
  however IDM up to 23.10.x only accepts certs with SAN and ignores DN.E (fixed now)

• key usage: if present, must be critical at least either digitalSignature or nonRepudiation (either works with IDM, too)
      cert extensions outlined in
      https://www.rfc-editor.org/rfc/rfc8550#section-4.4

• key type: RSA-2048 and up (4096 recommended) with algo SHA256withRSA  / SHA384withRSA / SHA512withRSA
          or ECC NIST P-256, P-384, P-521 with algo SHA256withECDSA / SHA384withECDSA / SHA512withECDSA
         CAB-Forum specifies key size and curves:https://cabforum.org/working-groups/smime/requirements/#615-key-sizes

• validity: adhering to CAB-Forum requirements:
      https://cabforum.org/working-groups/smime/requirements/#632-certificate-operational-periods-and-key-pair-usage-periods
      (825 days max at the time of writing)

hermodDeviceEnc

• included by default in config XML

• storage: pkcs12

java.lang.UnsupportedOperationException: PrivateExponent cannot be extracted, key must be used with the iD2 provider
  at com.id2tech.security.provider.PrivateRsaKeyImpl.getPrivateExponent(PrivateRsaKeyImpl.java:66) ~[common-8.5.3.jar:10.2.6]
  at org.bouncycastle.jcajce.provider.asymmetric.rsa.RSAUtil.generatePrivateKeyParameter(Unknown Source) ~[bcprov-jdk18on-1.73.jar:1.73.0]
  at org.bouncycastle.jcajce.provider.asymmetric.rsa.DigestSignatureSpi.engineInitSign(Unknown Source) ~[bcprov-jdk18on-1.73.jar:1.73.0]
  at java.security.Signature$Delegate.engineInitSign(Signature.java:1351) ~[?:?]
  at java.security.Signature.initSign(Signature.java:636) ~[?:?]
  at org.bouncycastle.operator.jcajce.JcaContentSignerBuilder.build(Unknown Source) ~[bcpkix-jdk18on-1.73.jar:1.73.0]
  at de.nexus.pkiutils.Digest.signerFor(Digest.java:40) ~[vps-pki_utils-0.279.0.jar:0.279.0]
  at de.nexus.pkiutils.certificate.CertAuthority.getSigner(CertAuthority.java:252) ~[vps-pki_utils-0.279.0.jar:0.279.0]
  at de.nexus.pkiutils.certificate.CertAuthority.createCertificate(CertAuthority.java:147) ~[vps-pki_utils-0.279.0.jar:0.279.0]
  at de.vps.act.processexecution.hermod.AbstractHermodInstallCertificatesAction.createCertCommand(AbstractHermodInstallCertificatesAction.java:110) ~[vps-process_execution-0.279.0.jar:0.279.0]

• no security relevance (a dummy certificate is used as transport container for the key-usage instead of putting it into e.g. a JSON field)

• trust does not matter

• versioning not needed (always uses the default (i.e. highest) version)

• no extensions (recommended to add KU digitalSignature for informative reasons)

• MAY be self-signed

• key type: RSA-2048 and up with algo SHA256withRSA  / SHA384withRSA / SHA512withRSA
          or ECC NIST P-256, P-384, P-521 with algo SHA256withECDSA / SHA384withECDSA / SHA512withECDSA        
          (for best performance: choose P-256 with SHA256withECDSA)

• validity: does not matter, still works when expired

SelfServiceJWTSigner

• storage: pkcs12, HSM (recommended)

• placeholder P12 is allowed if selfservice is not used

• key usage: does not matter (but digitalSignature recommended)

• MAY be self-signed

• versioning not needed (always uses the default (i.e. highest) version)

• trust does not matter (not needed in IDM keystore - engineSignEncryptConfig suffices)

• used internally by Operator only, both issues tokens and verifies them

• key type: RSA-2048 and up (4096 recommended), no ECC support!

• validity: does not matter, still works when expired

ContentProviderJWSSigner

• storage: pkcs12, HSM (recommended)

• placeholder P12 is fine if IDM is not used to provision Visual IDs

• must NOT be self-signed!

• versioning not needed (always uses the default (i.e. highest) version)

• key usage: (according to Martin Lund no special reqs, but put digitalSignature there)

• issuing CA cert must to be trusted by the app onto which to provision Visual IDs

• key type: RSA-2048 and up (4096 recommended), no ECC support!

• validity: at your discretion (make sure you do not forget to renew before the expiry date!), validity is checked on the SDK side

Misc. attestation key descriptors

• Names:

  • att_external-attestation-1 (mobile only)

  •  att_external-attestation-2 (mobile only)

  •  att_external-attestation-3 (mobile only)

  •  att_external-attestation-4 (mobile only)

  •  att_ATTESTATION (mobile+desktop, default)

• P12s have no private keys, only dummy cert where we only care about the public key

• storage: pkcs12, HSM (recommended)
  (for Utimaco first export cert from p12 to BINARY CER file, then import that into HSM)

• only public part with dummy cert generated by tool https://doc.nexusgroup.com/pub/configure-custom-attestation-keys

• we just verify based on the key, so the dummy cert and its validity does not matter

• key type: RSA-2048 and up (4096 recommended), no ECC support!

• algorithm param can be blank

• versioning supported (so technically you do not need to use multiple descriptors for rollover support...)

Descriptors not included by default

idopteAuthentication

• absent by default from XML configuration

• see Encoding using Idopte middleware in Identity Manager

• descriptor can be omitted entirely (not even a placeholder P12 needed) if Idopte middleware is not used, otherwise correct cert+keypair is required

• Idopte webapp cert, issued by Idopte based on CSR for a customer-generated keypair

  • CSR extensions: at least one placeholder SAN URI (which PDA will send as Origin header), e.g.

    • http://localhost:1234

• validity does matter (checked by Idopte middleware), regular renewal needed

• key type: RSA-2048, feedback from Idopte what else they would support pending....

• algorithm: NONEwithRSA

  •  (assuming no ECC support, otherwise it could also be NONEwithECDSA - required for correct signing of the challenge)

• storage: pkcs12

  • IdopteMiddleware.signEnvChallenge() always uses BC provider, probably should use IKeyDescriptor.getProviderForPrivateKey() instead

• versioning not needed (always uses the default (i.e. highest) version)

insideClientAuth

• absent by default from XML configuration

• see Encoding using Idopte middleware in Identity Manager

• descriptor can be omitted entirely (not even a placeholder P12 needed) if Idopte middleware is not used, otherwise correct cert+keypair is required

• inside server client auth

• algorithm attribute not used

  •  (we only use certificate and private key from the descriptor)

• storage: pkcs12

  • not clear if HSM is supported or not (see SSL.java)

• key type: RSA-2048 and up (4096 recommended)

  • unsure if ECC support or not...

• validity DOES matter, connection to Inside server will fail when expired

• unsure if self-signed certs would work (recommend to use CA)

• trust DOES matter - must be trusted by Inside server

• key usage: digitalSignature

• versioning not needed (always uses the default (i.e. highest) version)

Pin-Blob Decryption Descriptors

These do not have a specific name, but can be any descriptors listed in the pinBlobDecryptor.keyDescriptorNames property of system.properties .

• absent by default from XML configuration

• by default the property is empty, hence no descriptors  (and thus not even placeholder P12s) are needed, unless the feature is required

• see Encodings using Personal Desktop Client middleware in Identity Manager (section "Read encrypted PINs")

• keypairs of pin-encryption certificate for decrypting pin-blobs from pre-personalized cards to e.g. print pin letters for them

• algorithm: RSA

• key type: RSA-2048 (unsure if larger ones work), no ECC support!

• issued by CM

• storage: pkcs12, HSM (recommended)

• validity does not matter to IDM

• trust does not matter to IDM

• key usage: recommend keyEncipherment + dataEncipherment for information, but technically does not matter (IDM just needs the private key)

• we only use the private key

• versioning not needed (always uses the default (i.e. highest) version)

Additional Information

...

...

Smart ID Identity Manager

...

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

...