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	Value			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	Value			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	0x01: Go to online mode. 0x00: Go to offline mode.

Get IdP Configuration

This command is used to retrieve the current IdP (STA) configurations.

Tag	Length	Value			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	Value			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	Value			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	Value			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	Value			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	Value			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_CMD_SET_NEW_JWT.
		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	Value			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_JWTtags.
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	Value			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	Present for disconnect token. Absent for disconnect user.
		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: Disconnect user. On behalf of user is set. Only one user is disconnected.

Delete

This command is used to delete a token on the server.

Tag	Length	Value			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: TAG_CMD_CREATE_TOKEN

Token List

This command is used to retrieve all the tokens attached to a user from the server.

Tag	Length	Value			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	Value			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.

Example Output

{
  "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	Value			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.