Operation Encoding
ASN1 – BER are used as binary data encoding formats.
-
All numeric data (including big numbers) should be passed as BIG ENDIAN (most significant byte placed on lowest address).
-
All tags should start with high bit set to 1 – “Context-specific”. For example,
TAG_VERSION
(0x81) -
Tags that encapsulate other tags should have “P/C” bit set to “constructed” – (1). For example,
TAG_CMD_GET_STATUS
(0xB3)
All the requests have a response, and data for some of them.
For more information, refer to BER encoding.
Commands
The following commands are used during the application lifecycle:
Set Parameter
Check version
This command is used to request the service to check version of the server.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_SET_PARAMETER (0xB8) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Request for server communication version. |
Set online/offline
This command is used to request the service to go in online or offline mode. If offline mode is requested and there is no bundle then the service does not switch to offline mode.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_SET_PARAMETER (0xB8) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Request for server communication version. |
TAG_SET_ONLINE_OFFLINE (0xC0) |
var | 0x00 or 0x01 |
|
Get IdP Configuration
This command is used to retrieve the current IdP (STA) configurations.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_GET_IDP_CONFIG (0xBD) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Request for server communication version. |
Response Data
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_GET_IDP_CONFIG_RESPONSE (0xBE) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Request for server communication version. |
TAG_STA_CONFIGURATION (0x9F) |
var | STA configuration, refer to example below. | Request for status of token. |
Example Output
{
"idpvUrl": "https://10.164.45.197:5001/",
"idpvThumbprint": "fd5c411eaf03bd20c4ba1875ec5a86afb3e62225",
"tenantConfig": {
"tenantExchangePublicKeyType": "CKK_RSA",
"tenantExchangePublicKeyModulus": "wSvk+uFikPCELixLOcf64mgF41NdqXQC9R9qdTFkYy3nT2V9wfqrDKevXWshTJ+SSzRMMkGkvAddl/yjzUIHgCcHqMAZrwevulAOkf0kxHBWRR5RUT/7EwLLbK3sNzgg9PKTF6iJZvSJ4dHtVtzgp+rq6Pt0x1rVLzaocS46+GBTqAmDTs/4/r+EfewHwAQK0srCxxxZtOIUPMWS5sPuO6toxfgKtdn6u+so7xrdmjzgLkcpktEGUdi+0r+laEy02JplBjoHKgFLMpW7p2s/Egh4AueBLQslEGQu2ijMdYvHTBvVZM6hjrx6mEruoG9qBNyOPnlZ5QVAWRVGirUY4Q==",
"tenantExchangePublicKeyExponent": "AQAB",
"isAutoCardCreationEnabled": true,
"isOfflineFallbackEnabled": true
},
"idpConfig": {
"idpClientId": "939cffb6-ce7a-4df3-a71b-0a8c125b3cee",
"idpA": "ufKrpSMO2Al2xZSQPC2sPdBNmDB9FluxDJC47cLgm7roaO/tuLtVy1i44J52nPe9",
"idpIssuerUrl": "https://idp.safenetid.com/auth/realms/2H31DFOIEQ-STA",
"idpRedirectUrl": "https://www.idpvserver.com/redirect",
"jwtExpiration": "0000001e",
"idpThumbprint": "",
"identityProvider": "STA",
"refreshTokenExpirationDuration": "480",
"idpScope": "openid",
"jwtUserClaim": "preferred_username"
}
}
Get Status
This command is used to obtain the current service status.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_GET_STATUS (0xB3) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Request for server communication version. |
TAG_STATUS_OF
(0x8F) |
1 | TAG_TOKEN_CONNECTION_STATUS (0x93) | Request for status of token. | ||
TAG_USER (0x8A) |
1 | Current user ID (UTF8) | Optional. | ||
TAG_SUPPRESS_
NOTIFICATION
(0xC4) |
1 | True/False | To suppress the notification (optional). | ||
TAG_TOKEN_ID (0x9B) |
1 | Token ID | Optional. |
Response Data
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_STATUS_RESPONSE (0xB6) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Service communication protocol version. |
TAG_STATUS (0x8E) |
var | Refer to table above. | Refer to table above. | ||
TAG_TOKEN_STATUS_LIST (0x9A) |
var | Token list in json format. | Optional. Refer the example |
Connect
This command is used to connect a user or token (insert token operation).
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_CONNECT (0xB1) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_CONNECT_BEHAVIOR (0x9D) |
1 | 0 (Connect all Tokens) 1 (Connect default Token) 2 (Do not connect Token) |
Application Connect Behavior. | ||
TAG_USER (0x8A) |
var | Refer to table above. | User ID (user account). | ||
TAG_TOKEN_ID (0x9B) |
var | Token ID | Present only to connect a token (insert token). | ||
TAG_ON_BEHALF_OF_USER (0x8B) (optional) |
1 | 1 | Should be passed only in case of on-behalf connection. | ||
TAG_JWT (0xA7) |
var | TAG_JWT_TYPE (0x90) |
1 | 1 | 1 – For OpenID JWT. |
TAG_JWT_DATA (0x91) |
var | JWT Data | Access ticket. | ||
TAG_JWT_REFRESH_JWT (0x98) |
var | JWT Data | Refresh ticket. |
Set New JWT
This command is used to give a refreshed JWT to the service.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_SET_NEW_JWT (0xB4) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_CONNECT_BEHAVIOR (0x9D) |
1 | 0 (Connect all Tokens) 1 (Connect default Token) 2 (Do not connect Token) |
Application Connect Behavior | ||
TAG_ON_BEHALF_OF_USER (0x8B) (optional) |
1 | 1 | Should be passed only in case of on-behalf connection. | ||
TAG_USER (0x8A) |
1 | Current user ID (UTF8) | Optional | ||
TAG_TOKEN_ID (0x9B) |
1 | Token ID |
Token ID (token number). Only for |
||
TAG_JWT (0xA7) |
var | - | Refer to below sub tags. | ||
TAG_JWT (0xA7) |
var | TAG_JWT_TYPE (0x90) |
1 | 1 | 1 – For OpenID JWT. |
TAG_JWT_DATA (0x91) |
var | JWT Data | Access ticket. | ||
TAG_JWT_REFRESH_JWT (0x98) |
var | JWT Data | Refresh ticket. |
Create Token
This command is used to create a new token on the server.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_CREATE_TOKEN (0xBC) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_USER (0x8A) |
var | User ID (UTF8) | User ID (user account). | ||
TAG_ON_BEHALF_OF_USER (0x8B) (optional) |
1 | 1 | Should be passed only in case of onbehalf connection. | ||
TAG_JWT (0xA7) |
var | - | Refer to below TAG_JWT tags. |
||
TAG_JWT (0xA7) |
var | TAG_JWT_TYPE (0x90) |
1 | 1 | 1 – For OpenID JWT. |
TAG_JWT_DATA (0x91) |
var | JWT Data | Access ticket. | ||
TAG_JWT_REFRESH_JWT (0x98) |
var | JWT Data | Refresh ticket. |
Disconnect
This command is used to disconnect a user or token.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_DISCONNECT (0xB2) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_TOKEN_ID (0x9B) |
var | Token ID |
|
||
TAG_ON_BEHALF_OF_USER (0x8B) (optional) |
1 | 1 | Should be passed only in case of on-behalf connection. | ||
TAG_USER (0x8A) |
var | User ID (UTF8) |
User ID (user account). Present only if:
|
Delete
This command is used to delete a token on the server.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_DELETE (0xB9) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_TOKEN_ID (0x9B) |
var | Token ID |
Not present for the command:
|
Token List
This command is used to retrieve all the tokens attached to a user from the server.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_GET_TOKEN_LIST (0xBA) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Application communication protocol version. |
TAG_USER |
var | User ID (UTF8) |
RFU User ID (user account). |
Response Data
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
TAG_CMD_GET_TOKEN_LIST_RESPONSE (0xBB) |
var | TAG_VERSION (0x81) |
1 | 0x03 | Service communication protocol version. |
TAG_TOKEN_STATUS_LIST (0x9A) |
var | Token list in a JSON format. | Refer to the example below. |
For example,
{"NSmith":
{"UserID":"NSmith",
"listTokenInfo":{
"ea3f0d4d-d81d-4545-bfcf-a5f9b3a9ecb1":{
"TokenID":"ea3f0d4d-d81d-4545-bfcf-a5f9b3a9ecb1","TokenName":"Card1",
"IsConnected":true,"IsOffline":false,"OfflineUsername":null,
"WindowsUserName":null
},
"66e4b4ca-ac27-495b-be4d-2633e48b5b68":{
"TokenID":"66e4b4ca-ac27-495b-be4d-2633e48b5b68",
"TokenName":"Card2","IsConnected":true,"IsOffline":false,"OfflineUsername":null,"WindowsUserName":null},
}
Where,
- IsConnected: true, if the card is connected.
- IsOffline: true, if a card is in offline mode.
If the token list contains a token with the flag 'IsOffline', the service is in offline mode state. Otherwise, the service is in online mode.
Notify
This command is used to send notification events from the service to an application.
Tag | Length | Description | |||
---|---|---|---|---|---|
Sub Tag | Length | Value | |||
(0xC1)TAG_CMD_NOTIFY (0xB5) |
var | TAG_NOTIFICATION_TYPE (0x84) |
1 | Notification ID | Notification ID |
TAG_NOTIFICATION_DATA (0x82) (Optional) |
var | Event Data (Optional) | Data according to event type. |
Notification IDs:
TAG_GET_NEW_JWT
(0x92) – JWT expired. On receiving this notification ID, an application must request a new JWT.TAG_SRV_SWITCHED_OFFLINE
(0xC1) – The service is switched to offline mode because of the nonavailability of the network.
Tag Values
The following tables lists the tag values currently used in this application.
Table 1: Constructed Tags
Tags | Value (Hex) | Description |
---|---|---|
TAG_CMD_CONNECT |
0xB1 | Connects a user or token. |
TAG_CMD_DISCONNECT |
0xB2 | Disconnects a user or token. |
TAG_CMD_GET_STATUS |
0xB3 | To get current service status, this version supports connection status only. |
TAG_CMD_SET_NEW_JWT |
0xB4 | Updates new JWT on Client. |
TAG_CMD_NOTIFY |
0xB5 | Sent from Service to Application as result of internal event (e.g. JWT expiration). |
TAG_CMD_STATUS_RESPONSE |
0xB6 | This version supports connection status only. |
TAG_CMD_SET_PARAMETER |
0xB8 | To set the parameter. |
TAG_CMD_DELETE |
0xB9 | Deletes a token. |
TAG_CMD_GET_TOKEN_LIST |
0xBA | Provides list of token. |
TAG_CMD_GET_TOKEN_LIST_RESPONSE |
0xBB | Provides list of token answer. |
TAG_CMD_CREATE_TOKEN |
0xBC | Creates a token. |
TAG_CMD_IDP_CONFIG |
0xBD | To get the STA configuration. |
TAG_CMD_IDP_CONFIG_RESPONSE |
0xBE | To get the STA configuration answer. |
TAG_JWT |
0xBE | JWT set should contain access JWT and type of JWT. |
Table 2: Primitive Tags
Tags | Value (Hex) | Description |
---|---|---|
TAG_VERSION |
0x81 | Communication protocol version between service and application. |
TAG_NOTIFICATION_DATA |
0x82 | Provides the notification data. |
TAG_NOTIFICATION_TYPE |
0x84 | Provides the notification type. |
TAG_URL |
0x88 | Provides the server URL. |
TAG_TENANT |
0x89 | Provides the tenant. |
TAG_USER |
0x8A | Provides the username. |
TAG_ON_BEHALF_OF_USER |
0x8B | Generate token on behalf of user. |
TAG_STATUS |
0x8E | Provides status response. |
TAG_STATUS_OF |
0x8F | Get status of …. this version supports connection status only. |
TAG_JWT_TYPE |
0x90 | OpenID or … |
TAG_JWT_DATA |
0x91 | JWT – access ticket. |
TAG_GET_NEW_JWT |
0x92 | Notification to request new JWT |
TAG_TOKEN_CONNECTION_STATUS |
0x93 | For Get Status command. |
TAG_JWT_UPDATE_ENABLED |
0x95 | Configuration of JWT update. |
TAG_JWT_GOING_TO_EXPIRED_TIME |
0x96 | Configuration of JWT update. |
TAG_JWT_WAIT_FOR_UPDATE_TIME_INTERVAL |
0x97 | Configuration of JWT update. |
TAG_JWT_REFRESH_JWT |
0x98 | Refresh ticket – will be stored in Service. |
TAG_TOKEN_STATUS_LIST |
0x9A | Provides the token list. |
TAG_TOKEN_ID |
0x9B | Provides the token ID. |
TAG_TOKEN_NAME |
0x9C | Provides the token name. |
TAG_STA_CONFIGURATION |
0x9F | Provides the STA parameters. |
TAG_SET_ONLINE_OFFLINE |
0xC0 | Set service to offline/online mode. |
TAG_SRV_SWITCHED_OFFLINE |
0xC1 | Notification to inform that the service is switched to offline mode by itself. |
Table 3: Client Status
Tags | Value (Hex) | Description |
---|---|---|
SUCCESS |
0x00 | Command executed successfully. |
FAILED |
0x01 | Unspecified error encountered. |
TOKEN_NOT_CONNECTED |
0x02 | Token is not connected. |
TOKEN_CONNECTED |
0x03 | Token is connected. |
CONNECTION_SUCCESS |
0x04 | Connection is successful. |
CONNECTION_ERR_GENERAL |
0x05 | Connection failed. |
CONNECTION_ERR_WRONG_URL |
0x06 | Connection failed. |
CONNECTION_ERR_WRONG_USER |
0x07 | Connection failed. |
CONNECTION_ERR_WRONG_TENANT |
0x08 | Connection failed. |
CONNECTION_ALREADY_CONNECTED_SUCCESS |
0x09 | Token is already connected. |
JWT_UPDATE_SUCCESS |
0x0B | JWT update /refresh success else the token will be deleted. |
TOKEN_STATUS_NO_TOKENS |
0x0D | No token present. |
SERVICE_STOPPED |
0x0F | Service stopped working. |
DISCONNECT_SUCCESS |
0x10 | Token disconnected. |
UNSUPPORTED_VERSION |
0x11 | Service doesn’t support communication protocol version. |
DELETE_TOKEN_SUCCESS |
0x12 | Operation to delete a token successful. |
DELETE_TOKEN_FAILED |
0x13 | Operation to delete a token failed. |
CREATE_TOKEN_SUCCESS |
0x14 | Operation to create a token successful. |
CREATE_TOKEN_FAILED |
0x15 | Operation to create a token failed. |
SLOT_IS_NOT_AVALIABLE |
0x16 | No token present in the slot. |
LOGIN_SESSION_EXPIRED |
0x18 | Session with the server is expired. |
GET_CFG_FROM_SERVER_FAILED |
0x19 | Cannot retrieve the STA parameters. |
LOGIN_SESSION_FAILED |
0x20 | Issue with the server. |
AUTHORIZATION_FAILED |
0x21 | Authorization restricted when client connects using sws tenant. |
REFRESH_TOKEN_EXPIRED |
0x22 | Refresh token is expired. |
REMOTE_SERVER_NOT_REACHABLE |
0x23 | When Idpv server is not reachable. |
PROVISIONING_ERROR |
0x24 | Admin is trying to login but provisioning is already completed or user is trying to login but provisioning is still not completed. |
DISCONNECT_SUCCESS_REFRESH_TOKEN_EXPIRED |
0x25 | Displays notification is sys tray when refresh token is expired. |
TENANT_NOT_FOUND |
0x26 | The tenant is not found on the IDPV server. |
SERVER_NOT_HTTPS |
0x27 | The IDPV server URL has an HTTP instead of HTTPS. |
SERVER_NOT_TRUSTED |
0x28 | Trust relationship failed. |
SERVER_URL_MISMATCH |
0x29 | The certificate is found but the subject name does not match the URL of the IDPV server. |