Detailed Overview Of Descriptors

The engine’s descriptors are:

• encryptedFields: Encryption and decryption of fields in the Identity Manager database

• objectHistorySigner: Signing and verification of the object history

• configZipSigner: Signing and validation of the configuration files

• configZipEncrypter: Encryption of the configuration files

• signEmailDescriptor: Signing of emails

• hermodDeviceEnc: Creation of device encryption certificates that are used in Smart ID messaging

• ContentProviderJWSSigner: Creation of JWS signatures used for Smart ID messaging content provider API

• SelfServiceJWTSigner: Authentication of Smart ID Self-Service users to the Identity Manager backend

• att_*: Attestation for provisioning to Smart ID Mobile / Desktop Apps

• (arbitrary name): Decryption of PIN blobs from pre-personalized smart-cards created with the Personal Desktop Client

Here each descriptor is described in detail, including requirements how it shall be bootstrapped.

EncryptedFields

• use-case: Encryption and decryption of 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)

• 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

• general requirements:

  • placeholder keys/certs forbidden for productive use

    • confidentiality of database secrets would be at risk

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

• key requirements:

  • supported types:

    • 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

• use-case: Encryption of the configuration files

• configured in these applications

  • Identity Manager Admin / (earlier know as PRIME Designer)

  • Identity Manager Operator / (earlier known as PRIME Explorer)

• 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

  • NOTE: but you cannot reconfigure the asymCipher after exporting an encrypted ZIP, as config import of such a ZIP will fail

• general requirements:

  • placeholder allowed only if config ZIP encryption is disabled

    • after changing the key you cannot decrypt previously exported config ZIPs that use encryption

• key requirements:

  • supported types:

    • 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

• use-case: Signing and validation of the configuration files

• configured in these applications:

  • Identity Manager Admin

  • Identity Manager Operator

• certificate requirements:

  • if key usage extension is critical, then digitalSignature is required

  • issuing certificate has to be installed in the Identity Manager trust-store

  • certificate must not be self-signed

• storage: pkcs12, HSM (recommended)

• versioning: possible, but unnecessary (It is sufficient that the certificate that signed the old configs is trusted via the IDM truststore)

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

  • SHA-256

• general requirements:

  • placeholder allowed only if config ZIP signing and verification is disabled

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

  • if key usage extension is critical, then digitalSignature is required

  • issuing CA cert must be in IDM truststore

  • must not be self-signed!

  • validity considerations:

    • if expired download is blocked unless ZIP signing is disabled

    • if expired config upload will fail with the message "Verification failed. The certificate has expired."

• issues if not configured as above:

  • export is blocked unless unless ZIP signing is disabled

  • verification does not work, ZIP appears unsigned

ObjectHistorySigner

• use-case: Signing and verification of the object history

• configured in these applications:

  • Identity Manager Admin (technically not used here, but required for startup due to bean requirements - subject to change in future releases)

  • Identity Manager Operator

• configured in these special-case tools:

  • batch_re-sign_history

    (repair tool for history signature)

  • batch_migration_smartact_to_prime

    (for migration of data from Identity Manager's/PRIME's predecessor SmartAct)

• storage: pkcs12, HSM (recommended)

• versioning: supported (signatures created with old versions can still be verified)

• supported digest values: (changing the digest after history entries have been written requires a new version of the descriptor or startup will fail!)

  • SHA-256

  • SHA-384

  • SHA-512

• general requirements:

  • placeholder keys forbidden for productive use

    • integrity of history signature would be as risk

    • re-signing requires use of the batch_re-sign_history tool once the first history entry is created

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

  • if key usage extension is critical, then digitalSignature is required

  • may be self-signed

  • validity is ignored

  • certificate does not need to be trusted

SignEmailDescriptor

• use-case: send signed e-mails from IDM

• configured in this application:

  • Identity Manager Operator

• storage: pkcs12, HSM (recommended)

• versioning: supported, but unnecessary

• supported algorithm values:

  • for RSA keys only

    • SHA256withRSA  

    • SHA384withRSA

    • SHA512withRSA

  • for ECC keys only

    • SHA256withECDSA

    • SHA384withECDSA

    • SHA512withECDSA

• general requirements:

  • placeholders allowed only if email signing is not used

    • e-mail verification will fail if not issued by a trusted S/MIME CA

    • integrity of e-mails sent by IDM may be at risk if placeholder key is used

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096

    • ECC NIST P-256

    • ECC NIST P-384

    • ECC NIST P-521

• certificate requirements:

  • proper S/MIME certificate with configured IDM e-mail sender address in DN's E field and/or SAN RFC-822 entry

    • if subject DN email field is absent, SAN extension must be critical!

    • IDM up to 23.10.x only accepted SAN and ignoreed DN.E (fixed in IDM 24.R1)

  • must not be self-signed!

  • key usage: if present, must be critical and at least either digitalSignature or nonRepudiation

  • validity: adhering to CAB-Forum requirements from 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

• use-case: generate dummy certificate for transient key-pairs generated on a target device when provisioning Smart ID Mobile / Desktop App profiles (the certificates themselves are merely used as transport container for the key-usage parameter)

• configured in this application:

  • Identity Manager Operator

• storage: pkcs12

• versioning: possible, but unnecessary

• supported algorithm values:

  • for RSA keys only

    • SHA256withRSA  

    • SHA384withRSA

    • SHA512withRSA

  • for ECC keys only

    • SHA256withECDSA

    • SHA384withECDSA

    • SHA512withECDSA

• general requirements:

  • placeholders allowed

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096

    • ECC NIST P-256 (best performance)

    • ECC NIST P-384

    • ECC NIST P-521

• certificate requirements

  • may be self-signed

  • validity is ignored

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

  • certificate does not need to be trusted

SelfServiceJWTSigner

• use-case: Authentication of Smart ID Self-Service users to the Identity Manager backend

• configured in this application:

  • Identity Manager Operator

• storage: pkcs12, HSM (recommended)

• versioning: possible, but unnecessary

• general requirements:

  • placeholder keys forbidden for productive use

    • even if IDM SelfService is not deployed the related REST endpoints could face the risk of unauthenticated access

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

  • may be self-signed

  • validity is ignored

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

  • certificate does not need to be trusted

ContentProviderJWSSigner

• use case: signing content for Visual ID provisioning to Smart ID Mobile App

• configured in this application:

  • Identity Manager Operator (see Set up visual ID layout in Identity Manager)

• storage: pkcs12, HSM (recommended)

• versioning: possible, but unnecessary

• general requirements:

  • placeholder allowed only if Visual ID is not used

    • if the certificate configured here is not trusted by the end-user (mobile-) device, then Visual ID provisioning will fail

    • forgery of Visual ID possible if placeholder key is used and also trusted by the end-user device

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

  • must not be self-signed!

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

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

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

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

Misc Attestation Key Descriptors (att_…)

• default descriptor 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)

• use-case:

  • limit profile provisioning with Smart ID Mobile / Smart ID Desktop App to devices with certain keys (by default IDM includes certificates for the built-in keys of any Mobile and Desktop App installation)

• configured in these applications:

  • Identity Manager Operator

  • Identity Manager Admin (technically not used here, but required for startup due to bean requirements - subject to change in future releases)

• versioning: supported

• storage: pkcs12, HSM (recommended)

• general requirements:

  • default certificates do not need to be changed, unless you want to limit profile provisioning to certain devices

  • no private keys is configured for IDM, only each public key inside a certificate

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

  • when replacing, generated via tooling shown here: https://doc.nexusgroup.com/pub/configure-custom-attestation-keys

  • verification only uses the key, no part of the certificate is considered

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

  • validity is ignored

idopteAuthentication

• use-case: initial handshake with Idopte client-side middleware, see Encoding using Idopte middleware in Identity Manager

• configured in this application:

  • Identity Manager Operator

• storage: pkcs12

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

• supported algorithm value: NONEwithRSA

• general requirements:

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

  • PKI card encoding via the Idopte middleware will fail if missing or configured incorrectly

• key requirements:

  • supported type:

    • RSA 2048

• certificate requirements:

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

  • one customer-specific SAN URI (does not have to point to an existing website), e.g. https://idopte.customer.com (using hosts like localhost or 127.x.y.z is discouraged, as it severely restricts the maximum validity period of the certificate Idopte can issue)

  • validity: defined by the Idopte CA

insideClientAuth

• use-case: authenticate to the IN Groupe Inside Server, which performs certain cryptographic operations on behalf of IDM when using the Idopte middleware (see Encoding using Idopte middleware in Identity Manager)

• configured in this application:

  • Identity Manager Operator

• general requirements:

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

  • PKI card encoding via the Idopte middleware will fail if missing or configured incorrectly

• algorithm attribute not used

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

• versioning: not needed

• storage: pkcs12

• key requirements:

  • supported types:

    • RSA 2048

    • RSA 3072

    • RSA 4096 (recommended)

• certificate requirements:

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

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

  • must be trusted by Inside server

  • key usage: digitalSignature

Pin-Blob Decryption Descriptors

• descriptor names: can be any descriptor listed in the pinBlobDecryptor.keyDescriptorNames property of system.properties (or its Docker counterpart)

• use-case: decrypting pin-blobs from pre-personalized cards to e.g. print pin letters for them (see Encodings using Personal Desktop Client middleware in Identity Manager (section "Read encrypted PINs")

• configured in this application:

  • Identity Manager Operator

• supported algorithm value: RSA

• storage: pkcs12, HSM (recommended)

• versioning: not needed

• general requirements:

  • by default the property is empty, hence no descriptors  are needed, unless the feature is required

• key requirements:

  • supported types:

    • RSA 2048

• certificate requirements:

  • issued by Nexus Certificate Manager

  • validity ignored by IDM

  • does not need to be trusted by IDM

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