| Info |
|---|
This article is valid new for Smart ID Identity Manager 24.R1 or later. |
...
5.0.1. |
Descriptor overview
The engine’s descriptors are the following:
Descriptor | Description |
|---|---|
encryptedFields |
...
Encryption and decryption of fields in the Identity Manager database | |
configZipEncrypter |
...
Encryption of the configuration files | |
configZipSigner |
...
Signing and validation of the configuration files | |
objectHistorySigner |
...
Signing and verification of the object history | |
signEmailDescriptor |
...
Signing of emails | |
hermodDeviceEnc |
...
Creation of device encryption certificates that are used in Smart ID messaging | |
SelfServiceJWTSigner |
...
Authentication of Smart ID Self-Service users to the Identity Manager backend | |
ContentProviderJWSSigner |
...
Creation of JWS signatures used for Smart ID messaging content provider API | |
idopteAuthentication |
...
Initial handshake with Idopte client-side middleware | |
insideClientAuth |
...
Authentication to the IN Groupe Inside Server | |
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 |
For detailed descriptions of each descriptorEach descriptor is described in detail in the sections below, including requirements on how it should shall be bootstrapped, see below.Expand
| title | EncryptedFields |
|---|
EncryptedFields
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
| Info |
|---|
Descriptor included in default configuration. Correct bootstrapping is required for productive use. Only dev- and test systems may use placeholders |
...
(for example |
...
created with bootstrap.zip package or the corresponding |
...
docker container). |
...
Use case
...
Encryption and decryption of fields in the Identity Manager database
required: always
Configured in the following applications
Identity Manager Admin
...
Identity Manager Operator
...
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
...
HSM (recommended)
...
pkcs12
Versioning
Not supported, always uses version 1supported
Supported asymClipher values
...
for For HSM:
RSA/ECB/OAEPWithSHA-384AndMGF1Padding
RSA/ECB/OAEPWithSHA-512AndMGF1Padding
for 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
ConfigZipEncrypter
...
| 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 container). |
...
Use case
...
Encryption of the configuration files
required: always
Configured in the following applications
Identity Manager Admin
...
Identity Manager Operator
...
Storage
HSM (recommended)
...
pkcs12
Versioning
Not supported, always uses version 1supported
Supported asymClipher values
...
for For HSM:
RSA/ECB/OAEPWithSHA-384AndMGF1Padding
RSA/ECB/OAEPWithSHA-512AndMGF1Padding
for For PKCS#12:
RSA/None/OAEPWithSHA384AndMGF1Padding
RSA/None/OAEPWithSHA512AndMGF1Padding
| Note |
|---|
...
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
...
| title | ConfigZipSigner |
|---|
ConfigZipSigner
...
| 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 container). |
...
Use case
...
Signing and validation of the configuration filesconfigured
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, HSM (recommended)
...
Storage
HSM (recommended)
pkcs12
Versioning
Possible, but unnecessary. (It is sufficient that the certificate that signed the old configs is trusted via the IDM truststore.)supported
Supported digest value
...
(selecting Selecting SHA-384 or SHA-512 only affects MANIFEST.MF, other parts use SHA-256 always.)
SHA-256
...
General requirements
...
...
Placeholder allowed only if config ZIP
...
encryption 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
ObjectHistorySigner
...
| 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 container). |
...
Use case
...
Signing and verification of the object historyconfigured
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 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
...
HSM (recommended)
...
pkcs12
Versioning
Supported (signatures created with old versions can still be verified)supported
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-512
...
General requirements
...
...
Placeholder allowed only if history verification is disabled (via
activitiHistoryCleanerJobTrigger.cronExpressionset to a date in the distant future
...
. See List of Identity Manager system properties and Quartz CronTrigger tutorial for more information)
...
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
...
If you plan on enabling it at a later date, it is recommended not to use a placeholder
...
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
SignEmailDescriptor
...
| 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 container). |
...
use-case: send signed e-mails from IDM
...
Use case
Send signed emails from IDM
Required
When email signing is configured
Configured in the following application
Identity Manager Operator
Storage
...
HSM (recommended)
...
pkcs12
Versioning
Supported, but unnecessarysupported
Supported algorithm values
...
for For RSA keys only:
SHA256withRSA
SHA384withRSA
SHA512withRSA
for For ECC keys only:
SHA256withECDSA
SHA384withECDSA
SHA512withECDSA
...
General requirements
...
...
Placeholders allowed only if email signing is not used
...
Email verification will fail if not issued by a trusted S/MIME CA
...
Integrity of
...
emails 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
...
email 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
...
Broken support for DN.E
...
is fixed in IDM
...
5.0.0.
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
...
| title | hermodDeviceEnc |
|---|
hermodDeviceEnc
...
hermodDeviceEnc
| Info |
|---|
Descriptor included in default configuration. Bootstrapping required for technical reasons, but with relaxed security requirements compared to other use |
...
cases. |
...
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
Configured in
...
the following application
...
Identity Manager Operator
Storage
...
pkcs12
Versioning
versioning: possiblePossible, but unnecessarysupported
Supported algorithm values
...
for For RSA keys only:
SHA256withRSA
SHA384withRSA
SHA512withRSA
for 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
SelfServiceJWTSigner
...
| Info |
|---|
Descriptor included in |
...
default configuration. Correct bootstrapping is required for productive use. Only dev- and test systems may use placeholders (for example |
...
created with bootstrap.zip package or the corresponding |
...
docker container). |
...
Use case
...
Authentication of Smart ID Self-Service users to the Identity Manager backendconfigured in this application:
Configured in the following applications
Identity Manager Operator
Storage
...
HSM (recommended)
...
pkcs12
Versioning
Possible, but unnecessary. general
General requirements
...
...
Placeholder keys forbidden for productive use
...
Even if Smart ID Self-Service 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
...
...
Maybe self-signed
...
Validity is ignored
...
Key usage is not checked (recommended for informational purposes: set digitalSignature)
...
Certificate does not need to be trusted
...
ContentProviderJWSSigner
ContentProviderJWSSigner
...
| 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 container). |
...
Use case
...
Signing content for Visual ID provisioning to Smart ID Mobile Appconfigured in this application:
Configured in the following applications
Identity Manager Operator (
...
See Set up visual ID layout in Identity Manager for more information.)
Storage
...
HSM (recommended)
...
pkcs12
Versioning
Possible, but unnecessary. general
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 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 (
...
that is, highest) version
...
)
Misc Attestation Key Descriptors (att_…)
| Info |
|---|
...
Descriptors included in |
...
default configuration. |
...
Correct bootstrapping may be required for productive use, depending on the use case. Replacement of the default certificates is optional. |
...
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
...
...
Verify Certification Signing Requests (CSR) from Smart ID Mobile/Smart ID Desktop App.
...
Optionally limit profile provisioning with Smart ID Mobile/Smart ID Desktop App to certain devices, for example
...
company devices. This can be done by using Mobile/Desktop apps with custom private keys and configuring the corresponding public keys
...
in Identity Manager (by default
...
Identity Manager includes certificates for the built-in keys of any Mobile and Desktop App installation)
...
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
HSM (recommended)
...
general requirements:
...
pkcs12
Versioning
Supported
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
...
Identity Manager, 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:
...
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
| Info |
|---|
...
Descriptor not present by default |
...
, can be ignored unless the Idopte middleware is used for PKI card production. |
...
Use case
Initial handshake with Idopte client-side middleware, see Encoding using Idopte middleware in Identity Manager configured
Configured in
...
the following application
...
Identity Manager Operator
Storage
...
pkcs12
Versioning
versioning: not Not supported (always uses the default (i.e. that is, highest) versionsupported
Supported algorithm
...
values
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 types
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), 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: defined by the Idopte CA
...
insideClientAuth
| Info |
|---|
...
Descriptor not present by default |
...
, can be |
...
skipped unless the Idopte middleware is used for PKI card production. |
...
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:
Configured in the following applications
Identity Manager Operator
...
general requirements:
...
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 attribute not used
(
...
We only use certificate and private key from the descriptor)
...
versioning: not needed
...
storage: pkcs12
key requirements:
...
Key requirements
Supported types
RSA 2048
RSA 3072
RSA 4096 (recommended)
...
Certificate requirements
...
...
Validity DOES matter, connection to Inside server will fail when expired
...
Recommend to use a CA, unclear if self-signed certificates work
...
Must be trusted by Inside server
...
Key usage: digitalSignature
...
Pin-Blob Decryption Descriptors
Pin-Blob Decryption Descriptors
...
| Info |
|---|
Descriptors not present by default, can be skipped unless pin-blobs from pre-personalized cards (using Personal Desktop Client/KGS) |
...
have to be decrypted. |
...
Descriptor names
...
Can be any descriptor listed in the pinBlobDecryptor.keyDescriptorNames property of system.properties (or its Docker docker counterpart)use-case: decrypting
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 this application:
Configured in the following applications
Identity Manager Operator
...
supported algorithm value: RSA
...
storage: pkcs12, HSM (recommended)
...
versioning: not needed
general requirements:
...
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 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)
Alternative:
WORK IN PROGRESS - TRYING TO DISPLAY INFO IN ANOTHER WAY. PERHAPS A TABLE?
...
Descriptor
...
Included in default configuration
...
Use case
...
Required
...
Configurations
...
Storage
...
Versioning
...
Other
...
Requirements
...
EncryptedFields
...
This descriptor is included in the default configuration.
Correct bootstrapping is required for productive use.
Only dev- and test systems may use placeholders, for example, created with bootstrap.zip package or the corresponding Docker container.
...
Encryption and decryption of fields in the Identity Manager database
...
Always
...
Configured in the applications
Identity Manager Admin (previously known as PRIME Designer)
Identity Manager Operator (previously known as PRIME Explorer)
Configured in 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
...
pkcs12,
HSM (recommended)
...
not supported, always uses version 1
...
Supported asymClipher values:
for HSM
RSA/ECB/OAEPWithSHA-384AndMGF1PaddingRSA/ECB/OAEPWithSHA-512AndMGF1Padding
for PKCS#12
RSA/None/OAEPWithSHA384AndMGF1PaddingRSA/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
...
This descriptor is included in the 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 container).
...
Encryption of the configuration files
...
Always
...
Identity Manager Admin / (earlier know as PRIME Designer)
Identity Manager Operator / (earlier known as PRIME Explorer)
...
pkcs12, HSM (recommended)
...
not supported, always uses version 1
...
Supported asymClipher values:
for HSM
RSA/ECB/OAEPWithSHA-384AndMGF1PaddingRSA/ECB/OAEPWithSHA-512AndMGF1Padding
for PKCS#12
RSA/None/OAEPWithSHA384AndMGF1PaddingRSA/None/OAEPWithSHA512AndMGF1Padding
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
...
This descriptor is included in the 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 container).
...
Signing and validation of the configuration files
...
-
...
Identity Manager Admin
Identity Manager Operator
...
pkcs12,
HSM (recommended)
...
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-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
...
This descriptor is included in the 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 container).
...
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)
...
pkcs12,
HSM (recommended)
...
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 allowed only if history verification is disabled (via
activitiHistoryCleanerJobTrigger.cronExpressionset to a date in the distant future, see List of Identity Manager system properties and Quartz CronTrigger tutorial )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
if you plan on enabling it at a later date, it is recommended not to use a placeholder
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
...
Additional information
For more information, see Encrypt configuration files in Identity Manager.