Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor

This article describes the Smart ID Desktop App metadata tool. The tool is available for download from version 1.3.5 of Smart ID Desktop App.

Excerpt
With the tool you can gather information about Smart ID Desktop App metadata for backup or in order to investigate issues with Smart ID Desktop App. The tool also allows you to easily modify Smart ID Desktop App settings. This can be used to customize Smart ID Desktop App settings directly with the app installation, or to restore it.

The tool is not a part of the installation, but can be downloaded from the same area that Smart ID Desktop App is downloaded from (Nexus Support portal).

Since version 1.4.0 of Smart ID Desktop App, there are two versions of the app:

  • store - Smart ID Desktop App is downloaded from Microsoft Store
  • sideload - Smart ID Desktop App is downloaded from Nexus Support portal and installed with sideloading enabled


Note

The sideload version is deprecated from version 1.6.0 of Smart ID Desktop App. Read more about this here: Release note Smart ID Desktop App 1.6.0 and here: Install and upgrade Smart ID Desktop App.

See also the prerequisites below regarding what version of Smart ID Desktop App is required.

Download the tool

Expand
titleDownload the Smart ID Desktop App metadata tool

The tool is distributed as self contained binary (no install required). You can download the file, MetadataTool.exe, from Nexus Support portal.

Run the tool via command line

Expand
titleRun the tool via command line
  1. Go to the folder that includes the binary file (MetadataTool.exe):

    Code Block
    cd <folder_path>


  2. Run MetadataTool.exe with the desired options (see "Options" section below).
    1. Use MetadataTool.exe --help to view all options.
    2. To show log information, use the option -v or --verbose

      Code Block
      titleExample: Run metadata tool with logging enabled
      MetadataTool.exe -d -v


Anchor
option
option

Expand
titleOptions for MetadataTool.exe

These are the options for MetadataTool.exe:

OptionTypeDescription
-i, --importStringPath to the json file with import data.
-c, --cleanSwitch

Can be used as an additional parameter with import. If selected it restores the app to factory settings prior to import.

-d, --dumpSwitchOutputs Smart ID Desktop App metadata as json string.
-t, --installtypeStringEither store or sideload. Need only when both variants of Smart ID Desktop App are installed.
-m, --migrateToStoreFromSideloadSwitchStore version metadata are replaced by those of sideload version. All store version metadata will be lost.
-n, --migrateToSideloadFromStoreSwitchSideload version metadata are replaced by those of store version. All sideload version metadata will be lost.
-v, --verboseSwitchDisplays log details.
-s, --SignJsonStringOutputs json file with signed secure value and PC info. Requires access to Nexus Azure key vault.
-g, --GetComputerInfoSwitchOutputs computer info relevant to secure value import.
--help
Displays the help screen.
--version
Displays version information.


Gather information about Smart ID Desktop App settings for backup and debug purposes

Expand
titlePrerequisites
  • Downloaded MetadataTool.exe
  • Smart ID Desktop App version later or equal to 1.3.0.


Expand
titleGather information in json file

To gather information about the Smart ID Desktop App settings, use one of these methods:

  • Print the settings to the console, or
  • Export the settings into a file.

Print the Smart ID Desktop App settings to the console

  1. To print the Smart ID Desktop App settings to the console in json format, use the following command:

    Code Block
    MetadataTool.exe -d

    or

    Code Block
    MetadataTool.exe --dump


    Note

    When both variants of Smart ID Desktop App are installed (store and sideload) specify the installtype parameter (-t), values can be store or sideload.

    Example when Desktop App was downloaded from Microsoft store:

    Code Block
    titleExample: App downloaded from Microsoft Store
    metadatatool.exe -d -t store

    Example when Desktop App was downloaded from Nexus support portal and installed with sideloading enabled: 

    Code Block
    titleExample: App installed with sideloading enabled
    metadatatool.exe -d -t sideload



Export the Smart ID Desktop App settings into a file

  1. To export the Smart ID Desktop App settings into a file (saved in the folder that includes the binary file), use the following command:

    Code Block
    MetadataTool.exe -d > output_file_name.json 

    or

    Code Block
    MetadataTool.exe --dump > output_file_name.json


Note

When exporting Smart ID Desktop App metadata into a file DO NOT USE the verbose option.



Expand
titleOutput format of the json file

Data is organized into these groups.

  • AppData (UWP appdata - not to be modified)
  • Settings (user adjustable PDA settings)
  • Profiles (profile data)
  • Secured Parameters (adjustable only in cooperation with Nexus personnel)

Modify or restore Smart ID Desktop App settings

You can import a file with settings to change the configuration of Smart ID Desktop App.

Expand
titlePrerequisites
  • Downloaded MetadataTool.exe
  • Smart ID Desktop App version later or equal to 1.3.5.
  • It is strongly recommended to backup the Smart ID Desktop App settings before you continue.


Expand
titlePrepare the json file

These are the structural options for the json file.

  • The json file can have the same format as the json that was dumped when gathering information, as described above:

    Code Block
    titleExample: Full json file
    collapsetrue
    {
      "Appdata": {
        "currentVersion": "0.10.41.0",
        "FirstUseTime": 132284845977922598,
        "FirstVersionInstalled": "0.10.41.0",
        "IsFirstRun": true
      },
      "Settings": {
        "AlwaysFlushLogFile": "true",
        "ImportP12Target": "TPM",
        "KeyProtLevel": "NoConsent",
        "LogLevel": "Trace",
        "MinimizeAfter": "false",
        "SignAndAuthenticateWithOwnCertificatesOnly": "false",
        "Theme": "Light",
        "WipeYubi": "false"
      },
      "Profiles": {
        "Profile-526f4c96-dc64-41a9-a87a-dae10cfadff0": {
          "Activated": "3/10/2020 4:33:58 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/9df91ea5-e243-45c5-af63-9fa150115b68",
          "CardIdentifier": "ffcdd17d-8227-40fb-b1e0-8d0c0d380d1b",
          "DeleteDisabled": "true",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "526f4c96-dc64-41a9-a87a-dae10cfadff0",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|pex-17dd3bd7-75ed-4a71-84a2-bcc85-07718|74f7ce30e86197ebf2131d2876e0c934255fd0db",
          "PinResetButtonDisabled": "false",
          "ReaderName": "Microsoft Virtual Smart Card 10",
          "SmartCardId": "526f4c96-dc64-41a9-a87a-dae10cfadff0",
          "Status": "Online",
          "Token": "e1bdd8b9-d405-4687-8710-61aa70febfe1",
          "Type": "VSC",
          "UserId": "userASS"
        },
        "Profile-87ac2824-bb9d-4c8f-98b1-308e6b188c52": {
          "Activated": "3/10/2020 3:54:14 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/60715a91-45d4-4a34-90c3-d9d327f902ec",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "87ac2824-bb9d-4c8f-98b1-308e6b188c52",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|ee5b50d6a4b8b24a19b9011d781c5bdf_090eae2c-b3cb-4fff-8ec8-70f4c344736b|8ee194c6dd374fd3810fcadb2bbfb981eeb7aaf0",
          "PinResetButtonDisabled": "false",
          "ReaderName": "",
          "SmartCardId": "87ac2824-bb9d-4c8f-98b1-308e6b188c52",
          "Status": "Online",
          "Token": "426473a7-6e4e-4fb3-8896-5a285f94c4b4",
          "Type": "Software",
          "UserId": "OS19FF111801"
        },
        "Profile-8fd5a513-b19a-406b-be20-ac1a460fc8c0": {
          "Activated": "3/10/2020 3:55:39 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/e9a68660-c7f2-4e2d-806a-c94c94ac3439",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "8fd5a513-b19a-406b-be20-ac1a460fc8c0",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|C:\\Users\\david\\AppData\\Local\\Microsoft\\Crypto\\PCPKSP\\b5d414be8b38409f8567a0236ac4220c779c750b\\42bead215599cadb8c1c6c700dc0e63d800890f7.PCPKEY|4cf81c7f91a61a5b10bb3e8a56c0b5e9e72b87e6",
          "PinResetButtonDisabled": "false",
          "ReaderName": "",
          "SmartCardId": "8fd5a513-b19a-406b-be20-ac1a460fc8c0",
          "Status": "Online",
          "Token": "77948522-c705-4162-9566-452beb0c8d40",
          "Type": "TPM",
          "UserId": "OS191ff11801"
        },
        "Profile-9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133": {
          "Activated": "3/10/2020 3:13:19 PM",
          "BoxUri": "NA",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "ha",
          "EncryptionKeyDelete": "",
          "Id": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133",
          "Issuer": "Nexus CM Bootstrap CA",
          "KeyList": "FileP12|C:\\Users\\david\\AppData\\Local\\Microsoft\\Crypto\\PCPKSP\\b5d414be8b38409f8567a0236ac4220c779c750b\\b5338b9ac694b89601a5657f587c118081196203.PCPKEY|9b7acfb2ab13518d612c2abdef9be195aedbc158",
          "PinResetButtonDisabled": "",
          "ReaderName": "",
          "SmartCardId": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133",
          "Status": "Online",
          "Token": "NA",
          "Type": "File TPM",
          "UserId": "Security Officer 1"
        },
        "ProfileIdsList": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133 87ac2824-bb9d-4c8f-98b1-308e6b188c52 8fd5a513-b19a-406b-be20-ac1a460fc8c0 526f4c96-dc64-41a9-a87a-dae10cfadff0"
      }
    }
    
    


  • Or the json file can have a simplified structure (not using the groups):

    Code Block
    titleExample: Simplified json file
    collapsetrue
    {
        "currentVersion": "0.10.41.0",
        "FirstUseTime": 132284845977922598,
        "FirstVersionInstalled": "0.10.41.0",
        "IsFirstRun": true,
        "AlwaysFlushLogFile": "true",
        "ImportP12Target": "TPM",
        "KeyProtLevel": "NoConsent",
        "LogLevel": "Trace",
        "MinimizeAfter": "false",
        "SignAndAuthenticateWithOwnCertificatesOnly": "false",
        "Theme": "Light",
        "WipeYubi": "false",
        "Profile-526f4c96-dc64-41a9-a87a-dae10cfadff0": {
          "Activated": "3/10/2020 4:33:58 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/9df91ea5-e243-45c5-af63-9fa150115b68",
          "CardIdentifier": "ffcdd17d-8227-40fb-b1e0-8d0c0d380d1b",
          "DeleteDisabled": "true",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "526f4c96-dc64-41a9-a87a-dae10cfadff0",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|pex-17dd3bd7-75ed-4a71-84a2-bcc85-07718|74f7ce30e86197ebf2131d2876e0c934255fd0db",
          "PinResetButtonDisabled": "false",
          "ReaderName": "Microsoft Virtual Smart Card 10",
          "SmartCardId": "526f4c96-dc64-41a9-a87a-dae10cfadff0",
          "Status": "Online",
          "Token": "e1bdd8b9-d405-4687-8710-61aa70febfe1",
          "Type": "VSC",
          "UserId": "userASS"
        },
        "Profile-87ac2824-bb9d-4c8f-98b1-308e6b188c52": {
          "Activated": "3/10/2020 3:54:14 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/60715a91-45d4-4a34-90c3-d9d327f902ec",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "87ac2824-bb9d-4c8f-98b1-308e6b188c52",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|ee5b50d6a4b8b24a19b9011d781c5bdf_090eae2c-b3cb-4fff-8ec8-70f4c344736b|8ee194c6dd374fd3810fcadb2bbfb981eeb7aaf0",
          "PinResetButtonDisabled": "false",
          "ReaderName": "",
          "SmartCardId": "87ac2824-bb9d-4c8f-98b1-308e6b188c52",
          "Status": "Online",
          "Token": "426473a7-6e4e-4fb3-8896-5a285f94c4b4",
          "Type": "Software",
          "UserId": "OS19FF111801"
        },
        "Profile-8fd5a513-b19a-406b-be20-ac1a460fc8c0": {
          "Activated": "3/10/2020 3:55:39 PM",
          "BoxUri": "https://hermod-dev.go.nexusgroup.com/ms/e9a68660-c7f2-4e2d-806a-c94c94ac3439",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "TestProfile",
          "EncryptionKeyDelete": "",
          "Id": "8fd5a513-b19a-406b-be20-ac1a460fc8c0",
          "Issuer": "hermod-dev.go",
          "KeyList": "signer|C:\\Users\\david\\AppData\\Local\\Microsoft\\Crypto\\PCPKSP\\b5d414be8b38409f8567a0236ac4220c779c750b\\42bead215599cadb8c1c6c700dc0e63d800890f7.PCPKEY|4cf81c7f91a61a5b10bb3e8a56c0b5e9e72b87e6",
          "PinResetButtonDisabled": "false",
          "ReaderName": "",
          "SmartCardId": "8fd5a513-b19a-406b-be20-ac1a460fc8c0",
          "Status": "Online",
          "Token": "77948522-c705-4162-9566-452beb0c8d40",
          "Type": "TPM",
          "UserId": "OS191ff11801"
        },
        "Profile-9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133": {
          "Activated": "3/10/2020 3:13:19 PM",
          "BoxUri": "NA",
          "CardIdentifier": "",
          "DeleteDisabled": "false",
          "DeleteProfileAfterImport": "false",
          "DisplayName": "ha",
          "EncryptionKeyDelete": "",
          "Id": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133",
          "Issuer": "Nexus CM Bootstrap CA",
          "KeyList": "FileP12|C:\\Users\\david\\AppData\\Local\\Microsoft\\Crypto\\PCPKSP\\b5d414be8b38409f8567a0236ac4220c779c750b\\b5338b9ac694b89601a5657f587c118081196203.PCPKEY|9b7acfb2ab13518d612c2abdef9be195aedbc158",
          "PinResetButtonDisabled": "",
          "ReaderName": "",
          "SmartCardId": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133",
          "Status": "Online",
          "Token": "NA",
          "Type": "File TPM",
          "UserId": "Security Officer 1"
        },
        "ProfileIdsList": "9b7acfb2ab13518d612c2abdef9be195aedbc158_637194463990052133 87ac2824-bb9d-4c8f-98b1-308e6b188c52 8fd5a513-b19a-406b-be20-ac1a460fc8c0 526f4c96-dc64-41a9-a87a-dae10cfadff0"
    }


  • It is not necessary to specify all parameters: 

    Code Block
    titleExample: Only specify some parameters in the json file
    collapsetrue
    {
        "AlwaysFlushLogFile": "false",
        "ImportP12Target": "TPM",
        "KeyProtLevel": "NoConsent",
        "LogLevel": "Trace",
        "MinimizeAfter": "false",
        "SignAndAuthenticateWithOwnCertificatesOnly": "false",
        "Theme": "Light",
        "WipeYubi": "false",    
    }


    Note

    It is NOT recommended to use the clean option when modifying only some parameters. Note that the not mentioned user adjustable settings will be set to default, and the not mentioned profile settings are lost.



Expand
titleStructure of the json file

Individual parameter specifications -- Appdata

Should not be modified

Individual parameter specifications -- Settings

ParameterDescriptionRecognized valuesDefault value
AllowP12Import*Security feature that allows to disable P12 import from file.true, falsetrue
AllowedHermods*Security feature restricting the app communication only to the specified urls.String with comma separated list of urls-
SkipFailedP12sIf enabled, the P12 import process continues even if it fails to import individual P12s. P12s that cannot be imported are returned to Hermod in error message, but the process is otherwise finished as expected.true, falsefalse
ShowHiddenCerts

If the value is true, the app will show all profile certificates (a certificate is hidden if its keyid start with ".")

true, falsefalse
AlwaysFlushLogFileWrite into log file immediately (needs slightly more resources)true, falsefalse
GrantPermissionsCreateVSCThe value is true if a CreateVSC task exists, otherwise the value is false (cannot be changed using the metadata tool.true, false
ImportP12TargetPlatform to store the keys when importing P12 files.VSC, OS, TPM, YubiVSC
KeyProtLevelProtection level for key imported for P12 files.NoConsent, ConsentOnly, ConsentWithPassword,  ConsentWithFingerprintConsentWithPassword
WipeYubiWipe yubi before importing P12 file.true, falsefalse
LogLevelLog detailsNo, Trace, Debug, Info, Warn, Error, FatalNo
MinimizeAfterMinimize PDA after successful operationtrue, falsetrue
SignAndAuthenticateWithOwnCertificatesOnlyAllow only certificates installed by PDAtrue, falsefalse
ThemePDA themeDefault, Light, DarkDefault

* This parameter cannot be modified directly in the app (only through the Metadata tool).

Individual parameter specifications -- Profiles

ProfileIdsList: string of profile ids separated by space.

Individual parameter specifications -- Secured parameters

Secured parameters provide functionalities bearing security risks. They are cryptographycally protected and cannot be modified by a regular user. They can only be temporarily enabled with assistance of the the Nexus personnel who has access to Azure KeyVault "kv-keyvault-common-37226". Their purpose is to help during an integration or debugging process.

These are the parameters:

ParameterDescription
SecureLoggingIf enabled, Smart ID Desktop App logs all the sensitive information, which are normally discarded. This includes VSC admin keys, transport pins and all the sensitive encoding information.
UseHttpIf enabled, Smart ID Desktop App is allowed to talk to Hermod over http, which is normally disabled. This makes it easier to capture network communication, narrow down various network related issue and so on.


Expand
titleModify the secured parameters - can only be done by Nexus personnel
  1. Create a json file containing signed data, this is achieved in two steps:
    1. Prepare a json file containing parameter names and their values, together with a number of data needed for security reasons:
      1. DaysToExpiration(0-35, required parameter)
      2. User related data: PCName, DomainName, UserDomainName (at least one of the three needs to specified). See an example file here:

        Code Block
        titleExample: json file for modifying secured parameters
        collapsetrue
        {
          "Options": {
            "SecureLogging": "true",
        	"UseHttp": "true"
          },
          "DaysToExpiration": "10",
          "PCName": "DESKTOP-QE86VR1",
          "DomainName":,
          "UserDomainName": "DESKTOP-QE86VR1\\Tom"
        }


    2. Sign the file using metadata tool (requires access to Azure KeyVault "kv-keyvault-common-37226"):

      Code Block
      MetadataTool.exe -s dataSample.json > SignedParams.json


  2. Import the parameters:

    Code Block
    MetadataTool.exe -i SignedParams.json


  3. To display the values of the 3 parameters (PCName, DomainName, UserDomainName) corresponding to a particular user/pc: 

    Code Block
    MetadataTool.exe -g


Individual profile parameter specifications 

Note

Do NOT change profile data, as this may lead to unexpected behavior of Smart ID Desktop App.

When there is no specification for a given parameter then the acceptable values are arbitrary strings.

ParameterSpecificationExample value
Activatedstring "MM/dd/yyyy hh:mm tt""05/29/2019 05:50 AM"
BoxUri
"https://hermod-dev.go.nexusgroup.com/ms/e9a68660-c7f2-4e2d-806a-c94c94ac3439"
CardIdentifier

DeleteDisabled"true", "false""false"
DeleteProfileAfterImport"true", "false""false"
DisplayName
"TestProfile
EncryptionKeyDelete

Id
"8fd5a513-b19a-406b-be20-ac1a460fc8c0"
Issuer
"hermod-dev.go"
KeyList

PinResetButtonDisabled"true", "false""false"
ReaderName
"Microsoft Virtual Smart Card 0"
SmartCardId
"8fd5a513-b19a-406b-be20-ac1a460fc8c0"
Status"Online","Unavailable","Deleted","Incomplete","Unusable""Online"
Token
"77948522-c705-4162-9566-452beb0c8d40"
Type"VSC","Software","TPM","Yubi",""File VSC,"File Software","File TPM","File Yubi","LocalID06","mixed""TPM"
UserId
"OS191ff11801"



Expand
titleImport the json file
  1. To import a json file to Smart ID Desktop App, use the following command:

    Code Block
    MetadataTool.exe -i [import_json_path]

    or 

    Code Block
    MetadataTool.exe --import [import_json_path]


    Note

    When both variants of Smart ID Desktop App are installed (store and sideload) specify the installtype parameter (-t), values store or sideload.

    Example when Desktop App was downloaded from Microsoft Store:

    Code Block
    titleExample: App downloaded from Microsoft Store
    MetadataTool.exe -i [import_json_path] -t store

    Example when Desktop App was downloaded from Nexus support portal and installed with sideloading enabled:

    Code Block
    titleExample: App installed with sideloading enabled
    MetadataTool.exe -i [import_json_path] -t sideload



  2. To also clean the Smart ID Desktop App settings, when importing the json file, use the following command:

    Code Block
    MetadataTool.exe -i [import_json_path] -c

    or

    Code Block
    MetadataTool.exe --import [import_json_path] --clean


Migrate metadata between sideload and store version of Smart ID Desktop App

Metadata tool allows you to migrate metadata between the two versions in a simple way. 

Expand
titleMigrate metadata to store from sideload version
  1. To migrate metadata to store from sideload version:

    Code Block
    titleMigrate metadata to store from sideload
    metadatatool.exe --migrateToStoreFromSideload

    or

    Code Block
    metadatatool.exe -m


    Note

    All store version metadata will be lost (replaced by sideload version metadata).



Expand
titleMigrate metadata to sideload from store version
  1. To migrate metadata to sideload from store version:

    Code Block
    titleMigrate metadata to sideload from store
    metadatatool.exe --MigrateToSideloadFromStore

    or

    Code Block
    metadatatool.exe -n


    Note

    All sideload version metadata will be lost (replaced by store version metadata).


Merge profiles of both store and sideload app versions

You can export settings from the sideload app version into to store app version and vice versa. This example shows how to export settings from sideload to store.

Expand
titleMerge profiles
  1. Backup your metadata.
  2. Export settings from the sideload app version in a json file:

    Code Block
    titleExport settings
    metadatatool.exe -d -t sideload > out.json


  3. Import the settings into the store app version:

    Code Block
    titleImport settings
    metadatool.exe -i out.json -t store



This article is valid for Smart ID Desktop App 1.4.0 and later.

Related information