Comment: This article is new for Smart ID Identity Manager 24.R1.

Remember to update the release version number before publishing externally.

Descriptor overview

The engine’s descriptors are the following:

...

Each descriptor is described in detail in the sections below, including requirements how it shall be bootstrappedin the sections below, including requirements how it shall be bootstrapped.

Certain descriptors are used for optional features. If a certain feature (for example email signing) is not used in a given deployment, then you may configure the descriptor in question with a placeholder. Any PKCS#12 file containing a self-signed keypair will be sufficient in this case.

EncryptedFields

Use

...

case

Encryption and decryption of fields in the Identity Manager database

Required

Always

Configured in the following applications

...

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 Confidentiality of database secrets would be at risk

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

...

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

  • may May be self-signed

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

  • validity Validity is ignored

  • certificate Certificate does not need to be trusted

...

Use

...

case

Encryption of the configuration files

...

Always

Configured in the following applications

...

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 allowed only if config ZIP encryption is disabled

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

...

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

  • may May be self-signed

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

  • validity Validity is ignored

  • certificate Certificate does not need to be trusted

...

...

Use case

...

Signing and validation of the configuration files

...

Configured in

...

the following 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, Identity Manager Operator

Storage

• HSM (recommended)versioning: possible

• pkcs12

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-384 or SHA-512 only affects MANIFEST.MF, other parts use SHA-256 always.)

• SHA-256general

General requirements

...

• placeholder

  Placeholder allowed only if config ZIP

  signing and verification

  encryption is disabledkey

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• if

  If key usage extension is critical, then digitalSignature is required

• issuing

  Issuing CA cert must be in IDM truststore

• must

  Must not be self-signed

  !

• validity

  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 Issues if not configured as above:

  • export is blocked unless unless ZIP signing is disabled

  • verification does not work, ZIP appears unsigned

...

Info
Descriptor included in default configuration. Correct bootstrapping may be required for productive use, depending on the use - case. Dev- and test systems may use placeholders (for example created with bootstrap.zip package or the corresponding Docker docker container).

...

Use case

...

Signing and verification of the object history

...

Configured in

...

the following 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

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

• storage: pkcs12, HSM (recommended)versioning: supported

• pkcs12

Versioning

Supported (signatures created with old versions can still be verified)

...

Supported digest values

...

Note
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-512general

General requirements

...

• placeholder

  Placeholder allowed only if history verification is disabled (via activitiHistoryCleanerJobTrigger.cronExpression set to a date in the distant future

  , see

  . See List of Identity Manager system properties and Quartz CronTrigger tutorial for more information)

  • integrity

    Integrity of history signature would be as risk

  • re

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

  • if

    If you plan on enabling it at a later date, it is recommended not to use a placeholder

  key

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• if

  If key usage extension is critical, then digitalSignature is required

• may

  May be self-signed

• validity

  Validity is ignored

• certificate

  Certificate does not need to be trusted

SignEmailDescriptor

...

Use case

Send signed emails from IDM

Required

When email signing is configured

Configured in

...

the following application

...

• Identity Manager Operatorstorage: pkcs12,

Storage

• HSM (recommended)versioning: supported

• pkcs12

Versioning

Supported, but unnecessary

...

Supported algorithm values

...

...

For RSA keys only:

• SHA256withRSA  

• SHA384withRSA

• SHA512withRSA

  for

For ECC keys only:

• SHA256withECDSA

• SHA384withECDSA

• SHA512withECDSAgeneral

General requirements

...

• placeholders

  Placeholders allowed only if email signing is not used

  • e-mail

    Email verification will fail if not issued by a trusted S/MIME CA

  • integrity

    Integrity of

    e-mails

    emails sent by IDM may be at risk if placeholder key is used

  key

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096

• ECC NIST P-256

• ECC NIST P-384

• ECC NIST P-521certificate

Certificate requirements

...

• proper

  Proper S/MIME certificate with configured IDM

  e-mail

  email sender address in DN's E field and/or SAN RFC-822 entry

  • if

    If subject DN email field is absent, SAN extension must be critical

    !IDM up to 23.10.x only accepted SAN and ignored

  • Broken support for DN.E

    (

    is fixed in IDM

    24.R1)

    5.0.0.

• must not be self-signed

  !

• key

  Key usage:

  if

  
  If present, must be critical and at least either digitalSignature or nonRepudiation

  validity

• Validity:

  adhering

  
  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

...

the following application

...

• Identity Manager Operatorstorage:

Storage

• pkcs12

Versioning

...

Possible, but unnecessary

...

Supported algorithm values

...

...

For RSA keys only:

• SHA256withRSA  

• SHA384withRSA

• SHA512withRSA

  for

For ECC keys only:

• SHA256withECDSA

• SHA384withECDSA

• SHA512withECDSAgeneral

General requirements

...

• placeholders

  Placeholders allowed key

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096

• ECC NIST P-256 (best performance)

• ECC NIST P-384

• ECC NIST P-521certificate

Certificate requirements

• may

  May be self-signed

• validity

  Validity is ignored

• key

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

• certificate

  Certificate does not need to be trusted

SelfServiceJWTSigner

...

Use case

...

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

...

Configured in the following applications

• Identity Manager Operatorstorage: pkcs12,

Storage

• HSM (recommended)versioning: possible

• pkcs12

Versioning

Possible, but unnecessary.

...

General requirements

...

• placeholder

  Placeholder keys forbidden for productive use

  • even

    Even if Smart ID Self-Service is not deployed the related REST endpoints could face the risk of unauthenticated access

  key

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• may

  Maybe self-signed

• validity

  Validity is ignored

• key

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

• certificate

  Certificate does not need to be trusted

ContentProviderJWSSigner

...

Use case

...

Signing content for Visual ID provisioning to Smart ID Mobile App

...

Configured in the following applications

• Identity Manager Operator (

  see

  See Set up visual ID layout in Identity Manager for more information.)storage: pkcs12,

Storage

• HSM (recommended)versioning: possible)

• pkcs12

Versioning

Possible, but unnecessary.

...

General requirements

...

• placeholder

  Placeholder allowed only if Visual ID is not used

  • if

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

  • forgery

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

  key

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• must

  Must not be self-signed

  !

• key

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

• issuing

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

• validity

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

• versioning Versioning not needed (always uses the default (i.e. that is, 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-

Use case

...

• verify

  Verify Certification Signing Requests (CSR) from Smart ID Mobile/Smart ID Desktop App.

• optionally

  Optionally limit profile provisioning with Smart ID Mobile/Smart ID Desktop App to certain devices,

  e.g.

  for example company devices. This can be done by using Mobile/Desktop apps with custom private keys and configuring the corresponding public keys

  into IDM

  in Identity Manager (by default

  IDM

  Identity Manager includes certificates for the built-in keys of any Mobile and Desktop App installation)configured

Configured in

...

the following 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,

Storage

• HSM (recommended)

• general requirements:

  default

  pkcs12

Versioning

Supported

General requirements

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

• no

  No private keys is configured for

  IDM

  Identity Manager, only each public key inside a certificatekey

Key requirements

...

...

Supported types

...

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• when

  When replacing, generated via tooling shown here: 

  https://doc.nexusgroup.com/pub/configure-custom-attestation-keys verification

  Configure custom attestation keys

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

• key

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

• validity

  Validity is ignored

idopteAuthentication

...

Use case

Initial handshake with Idopte client-side middleware, see Encoding using Idopte middleware in Identity Manager

...

Configured in

...

the following application

...

• Identity Manager Operatorstorage:

Storage

• pkcs12

Versioning

...

Not supported (always uses the default (

...

that is, highest) version

...

Supported algorithm

...

values

• NONEwithRSAgeneral

General requirements

...

• descriptor

  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 incorrectlykey

Key requirements

...

...

Supported types

• RSA 2048certificate

Certificate requirements

...

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

• one

  One customer-specific SAN URI (does not have to point to an existing website),

  e.g.

  for example 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

  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:

...

Configured in the following applications

• Identity Manager Operator

Storage

• pkcs12

Versioning

Not needed

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 Algorithm attribute not used

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

• versioning: not needed

• storage: pkcs12

key requirements:

supported types:

Key requirements

Supported types

• RSA 2048

• RSA 3072

• RSA 4096 (recommended)certificate

Certificate requirements

...

• validity

  Validity DOES matter, connection to Inside server will fail when expired

• recommend

  Recommend to use a CA, unclear if self-signed certificates work

• must

  Must be trusted by Inside server

• key

  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

...

for example print pin letters for them (see Encodings using Personal Desktop Client middleware in Identity Manager (section "Read encrypted PINs")

...

Configured in the following applications

• Identity Manager Operator

• supported algorithm value: RSA

• storage: pkcs12, HSM (recommended)

• versioning: not needed

general requirements:

by

Storage

• pkcs12

Versioning

Not needed

Supported algorithm values

• RSA

General requirements

• By default the property is empty, hence no descriptors  are needed, unless the feature is requiredkey

Key requirements

...

...

Supported types

...

• RSA 2048certificate

Certificate requirements

...

• issued

  Issued by Nexus Certificate Manager

• validity

  Validity ignored by IDM

• does

  Does not need to be trusted by IDM

• key

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

Additional information

For more information, see Encrypt configuration files in Identity Manager.

...