Versions Compared

Key

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

This article describes extensions to the Smart ID Messaging API that are specific to Smart ID Desktop App (Personal Desktop App). For the full API description, see Hermod API


Expandall

API commands 

Expand
titleSign

Smart ID Desktop App supports both JWS and PKCS7 signatures. Not all the message properties that are described in the API documentation are supported by Smart ID Desktop App.


Expand
titleAuthenticate

Since Authenticate is a specific application of the Sign command. Therefore, the same applies as for the Sign command.


Expand
titleStartpinreset

This command is only used with Smart ID Desktop App.

Parameters

ParameterDescription

“smartcardid”

Defines which profile in Smart ID Desktop App that is targeted.

Response Parameters

ParameterDescription

“nonce”

This value is generated by Smart ID Desktop App and sent to the server to be encrypted by adminkey and returned using the Epin command as proof of adminkey possession.



Expand
titleEndpinreset

This command is only used with Smart ID Desktop App.

Parameters

ParameterDescription

“encryptednonce”

Encrypted nonce that was sent in Spin command to Hermod.

“smartcardid”

Defines which profile in Smart ID Desktop App that is targeted.

“newadminkey”

Optional.

If present, instead of initiating a PIN reset, it actually changes previous adminkey to the current one.

Hexencoded adminkey, which means 48 lowercase ASCI characters encoding 24 bytes of the new key.



Expand
titleCertificate

This command is used to import certificates.

Parameters

ParameterDescription

“smartcardid”

If the intended profile has it’s smartcardid different from profileid, you need to use smartcardid to identify it.

"desktopKeyProtectionLevel"

  • "NONE" means there is no confirmation action required to use the key.
  • "CONSENT" means you get a dialogue from Windows asking for simple confirmation.
  • "PASSWORD" means you need to enter it once you session to use it.
  • "BIOMETRICS" is for the future and will work depending on the capabilities of the device, where the keys are stored.

These options are only supported for software keys.



Expand
titlePing

This command is used to gather information about the device and the profile.

Parameters

ParameterDescription

“deviceinfo”:”true”/”false”

If true, the response will contain a set named deviceinfo with the following content:

  • “operatingsystem” - version of Windows 10
  • “name” - computer name
  • “model” - version of Smart ID Desktop App
“profileinfo”:”true”/”false”

If true, the response will contain an array with each set having the following content:

  • "guid" - a unique card identifier (a 16 byte random number tied to the given smartcard/token)
  • "name" - profile human readable name
  • "issuer" - issuer name
  • “pid” - profile id
  • “activated” - date of profile activation
  • “certificates” - comma separated list of cert hashes
“profileid”

Used if you want to receive profileinfo. Use a specific profileid to gather all profiles associated with it in a given installation.



Expand
titleProvision

The Provision command has many parameters that are specific to Smart ID Desktop App.

desktopExtensions is used to transfer data between Smart ID Desktop App and the server, without Hermod validating or checking it in any way. It has the form of an array with “key” and “data”, where key is as listed here after the colon and data given in the description.

Parameters:

ParameterDescription

“vscinfo”:”smartcardid”


“vscinfo”:”adminkey”
“vscinfo”:”oldadminkey”
“desktopExtensions”:”provisionreader”

“CreateTPM” means that Smart ID Desktop App attempts to create the virtual smartcard. This is only possible, if the running account has admin privileges.

“FreeTPM” means that Smart ID Desktop App attempts to find a virtual smart card that is available for use and then assign it to the profile. It also changes the adminkey from the oldadminkey to the “adminkey” and initiates a PIN reset operation.

“#TPM” works similarly as FreeTPM, but where # is an index of the virtual smart card to use.

“desktopExtensions”:”singleprofile”If set to true, provisioning is only allowed if there is no other profile created on the machine.
“desktopExtensions”:”deletedisabled”If this is set to true, the profile cannot be deleted locally and the only way to delete it is via remote delete command.
“desktopExtensions”:"disableactivatebutton"If set to true, the Activate button is not shown and a process is executed directly.
“desktopExtensions”:"disablepinresetbutton"If set to true, the Pin Reset button is not shown and a command is executed directly.
“desktopExtensions”:"congratsmessage"

Value: [message]. When this key is included, [message] is displayed upon successful provisioning and import cert is concluded instead of a default one.

"desktopKeyProtectionLevel"

  • "NONE" means there is no confirmation action required to use the key.
  • "CONSENT" means you get a dialogue from Windows asking for simple confirmation.
  • "PASSWORD" means you need to enter it once you session to use it.
  • "BIOMETRICS" is for the future and will work depending on the capabilities of the device, where the keys are stored.

These options are only supported for software keys.

“desktopExtensions”:”hybridprofile”

If the TPM does not accept a certain key to be imported via Smart ID Desktop App, the Hybrid Profile can be used. With the Hybrid Profile concept, one Virtual Smart Card (VSC) can store its associated keys in different storages (for example, TPM or soft key store) under the same VSC.

Storageprio defines the behaviour of the Hybrid Profile, for example, storageprio 1=TPM, storageprio 2=OS will try TPM and fallback to OS if TPM fails.

If this desktopExtensions is set, a Hybrid Profile is created,

“storageprios”
  • "YUBI" - means that PDA Smart ID Desktop App shall store keys on Yubikey token
  • "OS" - means that PDA Smart ID Desktop App shall store keys in the software (use software keys)
  • "APP" - means that PDA Smart ID Desktop App shall store keys on a virtual smartcard
  • “TPM” – means that PDA Smart ID Desktop App shall store keys individually on the TPM



Expand
titleDelete

The Delete command is used to delete a profile. Hermod also deletes the mailbox associated with the desktop.

Parameters:

ParameterDescription

"profileid”

Must match with the smartcardid.

“vscinfo”:”oldadminkey“

Old adminkey to change from.

“vscinfo”:”adminkey“

Adminkey to change to.

“vscinfo”:”smartcardid”

The ID of the profile to be deleted.

"confirmed“:“true“/“false“

If true, Hermod deletes the associated mailbox upon receiving OK from this message



This article is valid from Smart ID Desktop App 1.4.