API Description

The Linux and macOS Token Management API is written in C++. It uses the OIDC interface, also available in C++ using Qt environment.

The maximum connected virtual smart cards at the same time is fixed to 5.

Every API function returns an sResultTokenManager structure to indicate whether the requested operation succeeds or fails.

To know the list of error values, refer to Error Codes.

Commands

The following commands are used for the Linux client:

Set JWT Handler

This command is used to set JWT handler. The following points give information about the JWT handler:

• OIDC JWT retrieval procedure is implemented by the idpv_systray application (3rd party/Customer’s Application).

• The IDPV Linux Client libraries know when to trigger the JWT retrieval procedure.

• The idpv_systray application must implement a JWT Handler callback to allow the idpvTokenManager library to obtain/refresh its JWT when needed.

• The idpvTokenManager library calls the jwtHandlercallback during beginUserSession and when JWT is about to expire.

• The library calls the external application to refresh the JWT. Library is responsible for requesting a valid JWT when necessary.

• Input parameter is callback function.

The callback function has one parameter pTokenJwt of type sTokenJWT.

typedef struct
{
    bool result;                ///< true if result OK.
    char* access_token;         ///< access token string
    char* refresh_token;        ///< refresh token string
}sTokenJWT;

• if the parameter pTokenJwt is not NULL the application has to file the fields of sTokenJWT structure.
• If the parameter pTokenJwt is a NULL pointer then it indicates the JWT has expired (typically after 8 hours) and the virtual smart cards are no more available. The application should update the user interface to refect that. It is possible to call BeginUserSession() to start a new session.

The server configuration parameters are provided in the file config.json (IDPV_CONFIG_FILE_NAME) on the first callback call.

Example of config.json file:

{
"IDP a":"bd899a9d-1021-4a0f-ba44-c3ee72014a49",
"IDP redirect":"https://www.idpvserver.com:3001/redirect",
"IDP redirect MAC":"idpv://www.idpvserver.com/redirect",
"IDP client":"91509a8c-218c-4e8b-9ea1-707e983cbf1c",
"IDP":"https://idp.safenetid.com/auth/realms/2H31DFOIEQ-STA",
"idpScope":"openid"
}

• "IDP client" is the client identifier
• "IDP a" is the client identifier shared key
• "IDP" is the base URL. Append "/.well-known/openid-configuration" to get:
• "authorization_endpoint": authorization request URL
• "token_endpoint": URL used to request the access token to accessTokenUrl.
• "IDP redirect": redirect URL
• "IDP redirect MAC": redirect URL for macOS
• "idpScope": scope parameter to use in the OAuth request. Like: "openid"

Parameter

Input	Output
JWT handler callback	RV

For example,

  rv = SetJwtHandlerCpp(JWTHandler);

Begin User Session

This command is used to start a user session.

Parameters

Input	Output
Url, Tenant	RV

Where,

• Url is a string identifying the Server url.
• Tenant is a string identifying the associated Tenant, GUID based format.

For example,

  rv = BeginUserSession("https://x.y.z.t/”, "xxxxxxxx-yyyy-zzzz-tttt-uuuuuuuuuuuu");

End User Session

This command is used to terminate the existing user session.

Parameters

Input	Output
None	RV

For example,

  rv = EndUserSession();

List Tokens

This command is used to list the tokens belonging to the selected UserID.

Parameters

Input	Output
address of a pointer to char buffer	RV

For example,

  char *tokens = nullptr;
  rv = listTokens( & tokens );

Output,

The TokenID is the information required to manage token connection and disconnection.

Connect Token

This command connects the selected TokenID. Once connected, the corresponding virtual smart card is used to perform cryptographic operations.

Parameters

Input	Output
TokenID	RV

For example,

  rv = connectToken(TokenID);

Disconnect Token

This command disconnects the selected TokenID. Once disconnected, the corresponding virtual smart card is not able to perform cryptographic operations.

Parameters

Input	Output
TokenID	RV

For example,

  rv = disconnectToken(TokenID);

Error Codes

The sResultTokenManager structure is defined as:

  typedef struct
  {
      int status;                 
      std::string API_name;       
      std::string error_details;  
  }sResultTokenManager;   

The API returns the following values in sResultTokenManager::status field:

• #define APP_NO_ERROR 0

• #define APP_NONE_EMPTY_SLOT 100

• #define APP_KEY_MISMATCH 101

• #define APP_EMPTY_TOKEN_LIST 102

• #define APP_USER_SESSION_ALREADY_STOPPED 103