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:

1. After the application starts:

   1. 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.

   2. 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();
              }
      

2. Protect the data exchanged over the named pipe from eavesdropping using an encryption mechanism.

   1. The IDPV Client sends the TAG_CMD_ESTABLISH_ENCRYPTION command to establish encrypted communication:

      
          static public byte[] EstablishEncryptedPipeCommand(byte[] encrypteddata)
              {
              ASN1 cmd = new ASN1((byte)PipeTags.TAG_CMD_ESTABLISH_ENCRYPTION);
              cmd.Add(new ASN1((byte)PipeTags.TAG_VERSION, (byte)PipeVersion.COMMUNICATION_VERSION_3));
              if (encrypteddata != null)
                  cmd.Add(new ASN1((byte)PipeTags.TAG_CMD_SYSTRAY_ENCRYPTED_DATA, encrypteddata));
              return cmd.GetBytes();
              }
      

   2. The service sends the TAG_CMD_ESTABLISH_ENCRYPTION_RESPONSE command with the encrypted response data.

   3. The IDPV Client again sends the TAG_CMD_START_ENCRYPTION command with the encrypted data.

      
      static public byte[] StartEncryptedCommunication(byte[] encryptedData)
          {
          ASN1 cmd = new ASN1((byte)PipeTags.TAG_CMD_START_ENCRYPTION, encryptedData);
          cmd.Add(new ASN1((byte)PipeTags.TAG_VERSION, (byte)PipeVersion.COMMUNICATION_VERSION_3));
          cmd.Add(new ASN1((byte)PipeTags.TAG_CMD_SYSTRAY_ENCRYPTED_DATA, encryptedData));
          return cmd.GetBytes();
          }
      
      
      

3. When the Pipe connection is established:

   1. 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 //
      

      Add ASN1.cs file in the project. You can download this file from the following link.

   2. 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

4. The application sends the following Get IDP configuration command to get the STA parameters:

   Tag = TAG_CMD_GET_IDP_CONFIG

5. Retrieve the list of tokens by adding the following command:

   Tag = TAG_CMD_GET_TOKEN_LIST

6. Perform the following steps in online mode:

   1. 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.

   2. 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).

      1. 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.

      2. 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.

      1. After the token is received, it simulates the card insertion (connect to virtual driver and expose ATR).

      2. Service responds to the application with a success response (CONNECTION_SUCCESS).

   3. 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.

   4. When the service receives the APDU command, it checks if the JWT (access ticket) is expired.

      1. If the JWT expired during the service work, the service sends a notification command TAG_CMD_NOTIFY with notification type TAG_GET_NEW_JWT to the application.

      2. 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.

      3. 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.

7. Perform following steps in offline mode:

   1. The connection of the tokens is done automatically by the service, in case it detects network issues and offline tokens are present.

   2. User can only go to online mode, and cannot perform on behalf of the user operations.