Communication
This section describes the communication between the SafeNet IDPrime Virtual Application and the SafeNet IDPrime Virtual Service is based on a named Pipe in a bidirectional (in/out) mode.
Parameters to create pipe connection on client side:
- Pipe server name: "."
- Pipe name: F814B3A1-4306-455C-AF87-B807523CF78E
- Direction: in/out
- Pipe Options: asynchronous
- Buffer size: 4096 bytes
- Transmission Mode: message
Application Lifecycle
This section describes the lifecycle of the IDPV application. The following steps informs how to configure and manage the application:
-
After the application starts:
- It attempts to establish the pipe connection to the IDPV service. Once the connection is established, the application starts listening on Read of the Pipe.
- If “Read” throws an exception, the signet indicates that the service is down, and the application waits to reconnect.
static private byte[] GetStatusCommand(PipeTags status_of, byte[] username, byte[] tokenID, byte[] suppressNotificationFlag = null) { ASN1 cmd = new ASN1((byte)PipeTags.TAG_CMD_GET_STATUS); cmd.Add(new ASN1((byte)PipeTags.TAG_VERSION,(byte) PipeVersion.COMMUNICATION_VERSION_3)); cmd.Add(new ASN1((byte)PipeTags.TAG_STATUS_OF, (byte)status_of)); if (username != null) cmd.Add(new ASN1((byte)PipeTags.TAG_USER, username)); if (tokenID != null) cmd.Add(new ASN1((byte)PipeTags.TAG_TOKEN_ID, tokenID)); if(suppressNotificationFlag != null) cmd.Add(new ASN1((byte)PipeTags.TAG_SUPPRESS_NOTIFICATION, suppressNotificationFlag)); return cmd.GetBytes(); }
-
When the Pipe connection is established:
-
The application sends a
Get Status
command to receive the current service status and the communication protocol version.
byte[] message = GetStatusCommand(PipeTags.TAG_TOKEN_CONNECTION_STATUS, null, null, null); PipeClient.Write(message, 0, message.Length); // Start of Function // static private byte[] GetStatusCommand(PipeTags status_of, byte[] username, byte[] tokenID, byte[] suppressNotificationFlag = null) { ASN1 cmd = new ASN1((byte)PipeTags.TAG_CMD_GET_STATUS); cmd.Add(new ASN1((byte)PipeTags.TAG_VERSION, (byte)PipeVersion.COMMUNICATION_VERSION_ 3)); cmd.Add(new ASN1((byte)PipeTags.TAG_STATUS_OF, (byte)status_of)); if (username != null) cmd.Add(new ASN1((byte)PipeTags.TAG_USER, username)); if (tokenID != null) cmd.Add(new ASN1((byte)PipeTags.TAG_TOKEN_ID, tokenID)); if (suppressNotificationFlag != null) cmd.Add(new ASN1((byte)PipeTags.TAG_SUPPRESS_NOTIFICATION, suppressNotificationFlag)); return cmd.GetBytes(); } // End of Function //
Note: Add ASN1.cs file in the project. You can download this file from the following link. -
According to the received status, the application enables the appropriate commands in the application menu (Connect/Disconnect).
The following Get Status command is not mandatory for the communication process:
Tag =
TAG_CMD_GET_STATUS
-
-
The application sends the following
Get IDP configuration
command to get the STA parameters:Tag =
TAG_CMD_GET_IDP_CONFIG
-
Retrieve the list of tokens by adding the following command:
Tag =
TAG_CMD_GET_TOKEN_LIST
-
Perform the following steps in online mode:
-
After the Pipe connection is established, select either Connect or Connect on Behalf of the User option. Lifecycle remains same for both options.
This document describes only the Connect option. For information on the Connect on Behalf of the User option, refer to Token Provisioning.
-
In Connect option, the application receives an access ticket (JWT) from the IdP service. After JWT is successfully received, the application sends the
TAG_CMD_CONNECT
command to the IDPV service. The service receives this command and performs the following:If the token is already connected (user switches scenario).
-
If the previous token belongs to the same user (same userID, tenantID, URL, etc.), the service must respond with
CONNECTION_ALREADY_CONNECTED_SUCCESS
state. This state is not an error and the application can continue. -
If the token belongs to a different user, the service simulates the card unplug (disconnects virtual driver). Thereafter, the service continues with the connect operation.
Service accepts the new configuration data, and sends the
Get Token
request to the server.-
After the token is received, it simulates the card insertion (connect to virtual driver and expose ATR).
-
Service responds to the application with a success response
(CONNECTION_SUCCESS)
.
-
-
You can Disconnect service manually by the tray menu or it gets automatically disconnected by recognizing the situation when the user became inactive.
For example, User Logs out, User fast switch, etc.
The Service receives a
Disconnect
command and simulates a card unplug operation. -
When the service receives the
APDU
command, it checks if the JWT (access ticket) is expired.-
If the JWT expired during the service work, the service sends a notification command
TAG_CMD_NOTIFY
with notification typeTAG_GET_NEW_JWT
to the application. -
If the refresh ticket exists, the service checks if the refresh ticket is not expired. If the refresh ticket is valid, the service sends the refresh ticket as data with the tag:
TAG_NOTIFICATION_DATA
. -
When the application receive the
Get_New_JWT
notification with the refresh ticket, it refreshes the ticket and sends the new JWT and new refresh JWT to the service. If the application does not receive the refresh JWT, it requests a renewed JWT and sends a new JWT and new refreshed JWT to the service.
-
-
-
Perform following steps in offline mode:
-
The connection of the tokens is done automatically by the service, in case it detects network issues and offline tokens are present.
-
User can only go to online mode, and cannot perform on behalf of the user operations.
-