...
| Info |
|---|
This article includes updates for Smart ID Desktop App 1.12.1. |
This article describes extensions to the Smart ID Messaging API that are specific
...
to Smart ID Desktop App. For the full API description, see Hermod API.
API
...
commands
Sign
Additionally to JWS signatures, Smart ID Desktop App also
...
supports PKCS7, XML based signature
...
XMLDSIG and raw RSA signatures. Not all the message properties that are described in the API documentation are supported by Smart ID Desktop App.
...
Contact Nexus if you need more information regarding this.
...
Authenticate
Since Authenticate is a specific application of the Sign command. Therefore, the same applies as for the Sign command.
...
Startpinreset
This command is only used with Smart ID Desktop App.
If "driver", or "smartcardid", or both parameters are specified, a profile-less operation will be performed, for example, adminkey change, PIN reset, PUK change, or PIN change for a selected token not associated with an existing Smart ID Desktop App profile. However, if only the parameters "profileid" and "operation" are specified, the chosen operation is executed on a token associated with an existing profile within the app.
Parameters
Parameter | Description |
|---|---|
"driver" | Identifies the token in case of profile PIN reset. The value is json with two fields:
|
"operation" | If not specified, PIN reset is performed. Accepted values:
|
“smartcardid” | Unique minidriver-based token identifier. This parameter is used to identify the token in case of a profile-less operation. (To identify the token, it is enough to specify one of the fields “smartcardid” or “driver”). |
"profileid" | Identifies the profile within the Smart Id Desktop App, on which the operation is executed. (If the values for "smartcardid" and "profileid" identified with the profile are different, the value for "smartcardid" should be used.) |
Response Parameters
Parameter | Description |
|---|---|
“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. |
"transportedkey" | Onetime RSA key used for encoding of the new adminkey, which allows for its secure transmission. |
...
Endpinreset
This command is only used with Smart ID Desktop App.
Parameters
Parameter | Description |
|---|---|
"encryptedpayload" | Only used in case of adminkey change operation. The expected valued is the new adminkey in hex format, JWT encoded with RSA_OAEP and A128CBC_HS256. |
“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. |
...
Certificate
This command is used to import certificates.
Parameters
Parameter | Description |
|---|---|
“smartcardid” | If the intended profile has it’s smartcardid different from profileid, you need to use smartcardid to identify it. |
"desktopKeyProtectionLevel" |
|
...
These options are only supported for software keys. |
...
...
Ping
This command is used to gather information about the device and the profile.
Parameters
...
Parameter | Description |
|---|---|
“deviceinfo”:”true”/”false” | If true, the response will contain a set named deviceinfo with the following content:
|
“profileinfo”:”true”/”false” | If true, the response will contain an array with each set having the following content:
|
“profileid” | Used if you want to receive profileinfo. Use a specific profileid to gather all profiles associated with it in a given installation. |
...
...
Provision
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
...
Parameter | Description |
|---|---|
“vscinfo”:”smartcardid” | |
“vscinfo”:”adminkey” | |
“vscinfo”:”oldadminkey” | |
“desktopExtensions”: |
...
“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.
...
”singleprofile” | If set to true, provisioning is only allowed if there is no other profile created on the machine. |
“desktopExtensions”:”deletedisabled” | If set to true, the profile cannot be deleted locally and the only way to delete it is via remote delete command. |
“desktopExtensions”:”deleteafterimport” | This option is designed to support a specific use case of Yubico |
...
Yubikey provisioning in Windows kiosk mode, but may be useful elsewhere. Default it is set to false. If set to true, the certificates from the cert store are deleted and the profile itself is deleted from Smart ID Desktop App, upon successful conclusion of the ImportCertificate process. Note that reinserting |
...
a Yubico Yubikey token imports the certificates to the cert store, as the token also stores these certificates and shares this property with most physical smart cards. For information about importing certificates, see Import PKCS#12 file into Smart ID Desktop App. You can set Yubikey as Target for P12 import, see Advanced settings in Smart ID Desktop App. | |
“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. |
“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, |
"desktopKeyProtectionLevel" |
|
...
These options are only supported for software keys. | |
“storageprios” |
|
"wipeyubi" |
Default: true |
"wipe" | Same as for "wipeyubi" but for smart cards. The card must support wiping (that is, deleting the contents of a card and returning it to “factory” setting). This is not mandatory and not all cards support it. It is set by the token manufacturer. Default: false |
"straight_csrs" |
Default: false |
...
...
Delete
The Delete command is used to delete a profile. Hermod also deletes the mailbox associated with the desktop.
Parameters
...
Parameter | Description |
|---|---|
"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 |
...