Configure custom attestation keys

This article includes updates for Identity Manager 5.0.1.

Attestation keys are keypairs. The private keys are used by Smart ID Mobile App and Smart ID Desktop App to sign Certification Signing Requests (CSR) while the public keys are used by Smart ID Identity Manager to verify the requests.

As the default, built-in attestation keys can be found in any Smart ID Mobile App and Smart ID Desktop App installation, any device can install the app and try to request certificates. Configuring custom keypairs limits the devices that can request certificates to devices whose mobile or desktop app has the custom private key installed. The corresponding public keys can be configured into Identity Manager. This process consists of two steps:

Generate the PKCS#12 keystores.
To make the public keys available to Identity Manager, keystores that contain a certificate with the public key must be created. Nexus provide a tool that, given the modulus and public exponent of the public key in Base64 format (or an RSA JWK public key), creates the keystore.
Configure the sign and encrypt engine.
The sign and encrypt engine must have access to the keystores.

Prerequisites

Before you proceed with the configuration in Identity Manager, make sure that:

You have a mobile and/or desktop app with custom keys.
You have the public key material of these custom keys. That is, a string that looks similar to this, containing the public key in single-line JWK-based format ({"alg":"RS256", ...etc... ,"use":"sig"}):

JSON

PublicKey: {"alg":"RS256","e":"AQAB","keystate":"active","kid":"attestation_2023-11-02T08:29:08GMT","kty":"RSA","n":"trfHQvFlcFcOEaB9v9tF6R1NggU3o9ddhmDb3GnGuEA3bP8XaKOgIrvh-KFvinE0xATcZk_XQC9n5ORhm-c5KvfryAdCGM62SKoBonc7Av7Iu6YHdcJHjoSCvjNSsw6B3mPoWP6IRvzwZRKgLHIDeNCjA7r0oKCXQIr05IxMVjOSHD8FIxKsgDq8CaF6j-0UFYS92pV5Ok-20nXqLsGv_IHojqazIE3xnNi1kEmNJF4q2LmVFu6VFkegjCj_O78wIGTI9JUZJK1LNMU1BqSDUKek8iTGPgojurNLe31l4Uvpe4j1Gi52mVzEiCufKhJP4xJzK7EGeT9rtcuUf4tB5SmCT_t9WYz6MvJ7cwFJ9sF7bb8vwYU22qgKuyvGtQGIojoYXOyWzCj3E3ZJM_PQxOyJwRF8oCGYD1UjHGdDqzFVQa3NHKwTlz4vdnfRzAdcbG3tn0tB5OCA8vMrGZvP30QJx0MmBrxduLm4bN59FSPV1WLmFkYOVVdf0RIG-bNq65rrlMOOQcV5jasgBEy6alb5uh21ewWx0Ld2DOMosWCEDa6G02QRLZfWIAqMvRvZtfyrv5FRIVoAPUQTnFMH7AGNAQ0rEywYPRa0XE7viTspeLULRrltjzh5rg9YXVhNspyca4SqooZniVEDz2cqOSn7r37VXD_qz2DBKPtSXo8","n#len":"4096","storage":"APP","use":"sig"}

You have the Nexus keystore creator tool.
You have a JRE installed.

Step-by-step instructions

Generate PKCS#12 keystores

Keep the public key material at hand.
This example will use the following:

CODE

PublicKey: {"alg":"RS256","e":"AQAB","keystate":"active","kid":"attestation_2023-11-02T08:29:08GMT","kty":"RSA","n":"trfHQvFlcFcOEaB9v9tF6R1NggU3o9ddhmDb3GnGuEA3bP8XaKOgIrvh-KFvinE0xATcZk_XQC9n5ORhm-c5KvfryAdCGM62SKoBonc7Av7Iu6YHdcJHjoSCvjNSsw6B3mPoWP6IRvzwZRKgLHIDeNCjA7r0oKCXQIr05IxMVjOSHD8FIxKsgDq8CaF6j-0UFYS92pV5Ok-20nXqLsGv_IHojqazIE3xnNi1kEmNJF4q2LmVFu6VFkegjCj_O78wIGTI9JUZJK1LNMU1BqSDUKek8iTGPgojurNLe31l4Uvpe4j1Gi52mVzEiCufKhJP4xJzK7EGeT9rtcuUf4tB5SmCT_t9WYz6MvJ7cwFJ9sF7bb8vwYU22qgKuyvGtQGIojoYXOyWzCj3E3ZJM_PQxOyJwRF8oCGYD1UjHGdDqzFVQa3NHKwTlz4vdnfRzAdcbG3tn0tB5OCA8vMrGZvP30QJx0MmBrxduLm4bN59FSPV1WLmFkYOVVdf0RIG-bNq65rrlMOOQcV5jasgBEy6alb5uh21ewWx0Ld2DOMosWCEDa6G02QRLZfWIAqMvRvZtfyrv5FRIVoAPUQTnFMH7AGNAQ0rEywYPRa0XE7viTspeLULRrltjzh5rg9YXVhNspyca4SqooZniVEDz2cqOSn7r37VXD_qz2DBKPtSXo8","n#len":"4096","storage":"APP","use":"sig"}

If you are on a Windows machine and the environment variable JAVA_HOME is not set, edit createP12.bat and createP12fromJWK.bat and set JAVA_HOME to point to your Java installation.
Start the keystore creator tool.
You can either start it in a mode that expects a complete public key in JWK format (createP12fromJWK.bat / createP12fromJWK.sh), or in a mode that expects individual key components (createP12.bat / createP12.sh):
1. Start the keystore creator by executing createP12fromJWK.bat (on Windows) or createP12fromJWK.sh (on Linux). Then follow the instructions on the screen:
  1. Enter the public key in single-line JWK format.
  2. Enter the file name of the keystore to create, for example, "attestationKey.p12".
  3. Enter the keystore's password. You need to enter this twice for verification.
2. Start the keystore creator by executing createP12.bat (on Windows) or createP12.sh (on Linux). Then follow the instructions on the screen:
  1. Enter the public key exponent.
    This is denoted "e" in the key material. In the example above it is "AQAB".
  2. Enter the modulus.
    This is denoted "n". In the example above it is the long string: "trfHQ....tSXo8".
  3. Enter the file name of the keystore to create, for example, "attestationKey.p12".
  4. Enter the keystore's password. You need to enter this twice for verification.

You must set the password in the sign and encrypt engine's configuration as well. The tool will create a dummy certificate with the given public key. The certificate itself is not relevant, it just serves as a container for the public key.

The path to the created file will be printed on the screen. If the file failed to be created, see the note below.

If the file could not be created, for example, due to missing write permissions, the tool will print its contents on the screen as a long Base64 string. You can copy and paste this string in a file, Base64-decode it and store it. This will create the same file that could not be created in the first step. Alternatively, fix the problem and rerun the tool.

Configure the sign and encrypt engine

The keystore must be available to both Identity Manager Admin, for configuring processes with the created attestation keys, and Identity Manager Operator.

Do the following:

Copy the created keystore to a location where Identity Manager can access it.
Edit the sign and encrypt engine's configuration and create a new key entry referencing the keystore.
Create a new descriptor entry referencing this key entry. The name of the descriptor must be exactly the same as it is named in the Smart ID mobile app and Smart ID Desktop App, prepended with the string "att_".
The key name is denoted "kid" in the key material. In the example above, it is "attestation_2023-11-02T08:29:08GMT”, so the descriptor name would be “att_attestation_2023-11-02T08:29:08GMT“.

To use new keys for an existing descriptor, create a new descriptor or key entry with an incremented version. Signatures will be validated against all versions of the key, until a valid one is found. This is useful in case some clients still have the old keys.

During bootstrap, if you have custom keys, remove the default attestation keys from the engine's configuration.

Only clients with the custom attestation keys can generate keypairs. If you keep the default keys and add new keys under a newer version of the same descriptor, requests signed with the default keys will still be accepted.

Sample descriptor configuration

Example: attestation key

XML

<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
    <descriptors>
         <descriptor name="att_attestationKeyId" version="1">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_old" />
        </descriptor>
          <descriptor name="att_attestationKeyId" version="2">
            <type algorithm="SHA256withRSA" size="" result="" key="attestationKey_current" />
        </descriptor>
        <!-- others descriptors -->
    </descriptors>
    <keys>
        <key name="attestationKey_old">
            <type name="pkcs12" locationValue="classpath:attKeyOld.p12" pin="1234"/>
        </key>
         <key name="attestationKey_current">
            <type name="pkcs12" locationValue="classpath:attKeyCurrent.p12" pin="1234"/>
        </key>
        <!-- others keys -->
     </keys>
</engineSignEncrypt>