- This line was added.
- This line was removed.
- Formatting was changed.
This article describes the sign and encrypt engine in Smart ID Identity Manager (PRIME). 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
- Optional: Sign and validate config zip files
- Optional: Sign and encrypt emails
- Encrypt communication with Hermod devices
- Authenticate Smart ID Self-Service users to the Identity Manager backend
The sign and encrypt engine provides a consistent configuration of certificates for both signing and encryption. You can define algorithms and parameters and reference keys from an HSM or from PKCS#12 files.
The issuers of the referenced keys should also be trusted, that is, their certificates must be in the configured truststore. The default keystore location is <tomcat>/conf/prime.truststore, however a different location may be set in <tomcat>/webapps/<prime-application><application>/WEB-INF/classes/system.properties under the key
The supplied P12 files in Identity Manager, such as sign.p12, are merely examples and must be replaced for customer deployments.
Configuration file engineSignEncryptConfig.xml
Example configuration file
The following descriptors are predefined in the default file engineSignEncryptConfig.xml:
|Descriptor name||Description of use||Configurable?|
|Encrypt secret fields in Identity Manager, for example PIN codes in data pool definitions. It is not possible to change the keys once encrypted fields have been stored in the database. Version must be "1".|
Only change the referenced key during installation, i.e. before Identity Manager is started for the first time. If this descriptor is changed, then already encrypted fields stored in the database will not be readable.
|ConfigZipSigner||Sign the Identity Manager configuration archive. Verification of the configuration archive uses the certificate that was put in the archive during signing.|
Changes take effect after restart of Identity Manager. Versioning can be used as with the ObjectHistorySigner descriptor, but this may make the file more difficult to read.
|Sign and verify database history.|
|SignEmailDescriptor||Sign emails from Identity Manager.|
Changes take effect after restart of Identity Manager. Versioning can be used as with the SignEmailDescriptor descriptor, but this may make the file more difficult to read.
Changes take effect after restart of Identity Manager. Versioning can be used as with the hermodDeviceEnc descriptor, but this may make the file more difficult to read (and is also completely pointless in this particular case - see note to the left).
Authenticate Smart ID Self-Service users to the Identity Manager backend.
Changes take effect after restart of Identity Manager. Versioning can be used as with the SelfServiceJWTSigner descriptor, but this may make the file more difficult to read.
This is an example of a descriptor (taken from the file shown above in Example file engineSignEncryptConfig.xml), see the tables below the example for more information.
<descriptor name="ObjectHistorySigner" version="2"> <type algorithm="SHA-256" size="" result="" key="objectHistorySignerCert" /> </descriptor>
|name||Used by Identity Manager to refer to this descriptor. There might be different descriptors with the same name but with different versions.|
|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 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
For field encryption: a symmetric algorithm to be used, for example,
For JWT: an asymmetric algorithm, for example,
For signing: a signature or hashing algorithm to be used (for example,
For field encryption: size of the symmetric key, for example, 256.
For JWT: size of the asymmetric key, for example, 2048.
For field encryption: Output format. Currently, the only possible value is
|key||Refers to a key defined in the same document|
For field encryption: specific cipher description, for example,
When used with an HSM, you need to adjust the cipher format to be compatible with the JCE provider used for HSM access.
If this is missing, a random generated IV will be used. This is the recommended behaviour.
For migrating SmartAct or ProAct it is necessary to set a fixed IV here.
This is an example of a key (taken from the file shown above in Example file engineSignEncryptConfig.xml), see the tables below the example for more information.
<key name="objectHistorySignerCert"> <type name="pkcs12" locationValue="classpath:sign.p12" pin="1234"/> </key>
|name||Used by descriptors' key attribute to reference this key.|
|Attribute of the ||Description|
Type of storage. For example, pkcs12 and HSM are supported.
For a software keystore: place the keystore under web-inf/classes and set its location, prefixed with "classpath:", for example:
For an HSM, use the filename of the PKCS11 library, without filename extension, for example,
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
See Scramble sensitive data in Identity Manager files for details.
Identity Manager needs access to the old descriptors and certificates in order to verify history entries signed with them. To make a change:
- Create a new descriptor with the same name but increase its version number.
- To use a new PKCS#12 container, create a new key entry with a unique name and reference it using the key attribute of the new descriptor.
Identity Manager will now use the new descriptor for signing future entries. Verification will automatically use the correct descriptor, that is, older entries will use the old descriptor(s) while new ones will use the new one.
This is an example where the PKCS#12 container is changed.
<?xml version="1.0" encoding="UTF-8"?> <engineSignEncrypt> <descriptors> <descriptor name="ObjectHistorySigner" version="2"> <type algorithm="SHA-256" size="" result="" key="signCertV2" /> </descriptor> <descriptor name="ObjectHistorySigner" version="1"> <type algorithm="SHA-256" size="" result="" key="signCertV1" /> </descriptor> </descriptors> <keys> <key name="signCertV2"> <type name="pkcs12" locationValue="classpath:sign.p12" pin.encrypted="1234" /> </key> <key name="signCertV1"> <type name="pkcs12" locationValue="classpath:sign_expired.p12" pin="encrypted:h1AKH0MeF1mOUSW1s+9vN+MAeA=="/> </key> </keys> </engineSignEncrypt>